SREの藤原です。
MNTSQではセールス、コンサルティング、テクニカルサポートのメンバーなどが顧客からの問い合わせに回答する際に参照するセキュリティホワイトペーパーが存在しています。
このセキュリティホワイトペーパーを、これまではGoogle Docsにて管理していました。 これをマークダウン + GitHubリポジトリでの管理に移行したので、その事例エントリです。
Google Docsで管理する際に発生していた問題
Google Docs自体は共同編集ツールとしては非常に優れています。 一方で、社内で公式に参照する文書という観点では課題を抱えていました。
主な課題としては以下の2点です。
- 変更管理の難しさ
- 複数人で異なる変更を行う場合にそれぞれを個別に変更として取り込むことがGoogle Docsでは困難でした
- 最新版か否かの分かりづらさ
- Google Docs自体にも版管理機能はありますが、リリース版のファイルを個別で管理する必要があるなど少々面倒な側面があります。
- 特定のファイルが公式としての変更が加えられたものなのか、それとも変更は加えられているが、それがまだレビュー中なのか？といった判断が難しい（変更の提案機能などをつかうこともできるが、必ずしもそれを全員が使うわけでもありません）
解決策としてのGitHub管理
解決策は非常にシンプルでGoogle Docsではなく、GitHubでマークダウンとして管理するという方式にしました。
元のドキュメント自体もGoogle Docsでなければ困るような高度な機能を利用しているわけでもなかったため、マークダウンで実現可能な表現力で十分であるという判断のもと、マークダウン+GitHubに移行しました。
章ごとにマークダウンファイルを分割することで、変更のコンフリクトが起こりづらいようにしています。
以降では、GitHubに移行することによるメリットについて述べていきます。
メリット1: 変更管理がPRベースになった
GitHubに移行したことで、文書の変更がプルリクエスト（PR）ベースで管理されるようになりました。結果として以下を容易に実現できるようになりました。
- どの章を、誰が、なぜ変更したか、がコミットメッセージとPR説明に残ります
- レビュアーは差分（diff）を見て内容を確認できます
- マージ前に承認フローを設定することで、「誰でも勝手に書き換えられる」リスクを排除できます
これはコードのレビューとまったく同じフローだ。エンジニアにとっては馴染み深いプロセスなので、文書の品質管理がやりやすくなりました。
メリット2：Claude Codeで文書修正が容易になった
章ごとにマークダウンで分かれているため、Claude Codeを使った文書修正が非常にやりやすくなりました。
たとえば、まずは、キーワードのみをClaude Codeに与えて文章を出力した後に、文書内容を確認して、問題ないかといったことができるようになりました。またその修正結果はそのままGitのdiffとして確認でき、PRを作ってレビューするだけで取り込むこともできますし、他の人からのレビューもしやすくなります。
人が文章を記述するよりもClaude Codeの方が書き上げるまでにかかる時間は短く、文章の質ともより高いものになります。キーワードとおおよその文脈情報さえ与えれば、ほとんどの場合において、内容を確認して一部だけ修正することで改善できます。
メリット3: GitHub Actionsを使ったPDF出力と、リリース管理
「公式文書としての最新版管理」を実現するため、GitHub Actionsのワークフローを組みました。
仕組みは次の通りです。
- 任意のタイミングでリリース版作成のGitHub Actionsワークフローをトリガーします
- ワークフロー内でタグをきり、プレリリースを作成します
- マークダウンファイルを結合してpdfファイルを作成します
- 3で作成したpdfファイルを2で作成したプレリリースに成果物として付与します
ここで、プレリリースまでとしているのはpdfファイルの体裁などが崩れていないか？を確認したのちに、リリースに昇格することを意図しています。
GitHubリポジトリのリリースを見れば、最新版のドキュメントにたどり着けるようになります。
移行時の注意点
ただし、マークダウンに移行する際の注意点としては、以下の2点が挙げられます。
- 日本語フォント
- GitHub Actionsでは日本語フォントを明示的にインストールする必要があります。 fonts-noto-cjkなどをインストールして利用しましょう。
- pdfへの変換ツールの選定
- 本事例ではmd-to-pdfを利用しています。今回要求されている事例ではこれで要件を満たせていたため、問題はなかったのですが、高度な組版などが要求される場合はそれにフィットしたツール(PandocやVivliostyle.js、Re:VIEWなど)が必要になるかもしれません。
まとめ
ここまでGoogle Docsで管理されていたドキュメントをGitHub + マークダウン管理に移行した事例について述べました。これによって、ドキュメントの変更管理と最新版配布などが容易にできるようになりました。特に定期的な更新が発生しつつ、SSoTとして正確性が重要になる文書にはフィットするとおもいます。
本事例が文書管理に悩んでいる組織の参考となれば幸いです。
