GitHubとVitePressによる 開発ドキュメント運用
はじめに
いきなりですが、ドキュメントは少し目を離すだけで陳腐化していきます。それはもう見るも無惨な状態になってしまいます。これを回避するにはドキュメントを適切に管理・更新し続ける仕組みと忍耐力が必要です。
今回は、以前登壇した「ドキュメント管理を制する 陳腐化を防ぐための実践事例 Lunch LT」というイベントの発表内容をもう少し深堀りしつつ、記事としてまとめました。
なぜドキュメントは陳腐化するのか
ドキュメントの陳腐化を防ぐためには、まずはなぜドキュメントが陳腐化するのかを理解する必要があります。ドキュメントが陳腐化する理由は大きく分けて3つあると考えています。
1. 議論と更新が分離してしまっている
まず大前提としてドキュメントを更新する必要があるということは、そうなった理由があり必ず議論がなされているはずです。何も理由がなくドキュメントの更新が必要になることはないからです。
にもかかわらずドキュメントが更新されないのは、すべての議論が終わるのを待ってからドキュメントの更新をしようとしているからだと考えています。
こういった議論というのはすぐに結論が出るものばかりではなく、それだけでかなりの体力を必要とします。その後になってドキュメントの更新をしようとしたところで、なかなか手が動かず後回しになってしまうことは容易に想像がつきます。
議論の対象はドキュメントなのですから、その場でドキュメントを更新するようにすれば記憶も新しく更新の手間も改善されます。
2. ドキュメントの更新コストが大きい
仮にドキュメントの更新に取り掛かったとしても、更新コストが大きいとなかなか更新が進みません。
よくある例がExcel方眼やパワポスライドによるドキュメントです。これらは一見誰にでも扱えて編集も簡単そうに見えますが、本来ドキュメントを作成するためにあるものではありません。そのため、見た目を整えることに時間を取られてしまうなど、本来行いたい編集作業以外の作業に時間を取られてしまいます。
こうしたことが積み重なっていくと、ドキュメントの更新コストがどんどん大きくなってしまい、更新したくてもできないといった事態に陥ります。
いくら使い慣れたツールといっても本来の用途と異なる使い方は避けるべきです。
3. 直近の自分たちは困らないから
本来ドキュメントというのは開発を行う上で必須のものにもかかわらず陳腐化してしまうのは、陳腐化しても開発が進められるからです。なぜなら、ドキュメントを書いたり更新のための議論をしている本人たちの頭の中にはドキュメントの内容があるからです。
結果として、直近の自分たちはドキュメントが陳腐化していてもそれが大きな問題として顕在化しづらく、ドキュメントの更新が後回しにされてしまうのです。しかしそれも一時的なものでしかなく、開発が一段落ついたり、新しいメンバーが加わったりするとドキュメントの陳腐化による問題が時間差で顕在化してきます。
チームが小さければ小さいほど陥りやすい問題ですが、ここは意識して更新していく必要があります。
実際にあったドキュメントの陳腐化
ここで、実際に僕が経験してきたドキュメントの陳腐化の例を紹介します。
1. 読めない
読みたくても読めない・読む気が起きないドキュメントです。これはドキュメントの更新コストが大きかったり、適切なツールを使っていないときによくあります。
たとえば以下のようなものです。
- レイアウト崩れを諦めて文字がはみ出したExcel方眼
- 100枚近いスライドで構成されて激重になってしまったパワポスライド
- 大量の図形と小さい文字で埋め尽くされたホワイトボードツール
これでは読みたくても読めませんし、読む気すら起きません。読めないドキュメントは存在しないのと同じです。
2. 見つからない
いざドキュメントを読もうと思っても見つからないドキュメントです。これはドキュメントの管理方法が統一されていなかったり、そもそも整理されていないときによくあります。
たとえば以下のようなものです。
- ファイル名で検索しても似たファイルが大量にヒットする
- ファイル形式によってそもそも保存先が異なる
- そもそも検索にヒットしない
見つからなければ読むことはできません。見つからないドキュメントは存在しないのと同じです。
3. 知らない間に更新されている
開発過渡期でとくに多いのが、知らない間に更新されているドキュメントです。これはドキュメントのバージョン管理や更新サイクルを明確にしていないときによくあります。
たとえば以下のようなものです。
- 実装に入った後にドキュメントが知らないところで更新されていた
- 細かな変更が断続的に発生して変更を負えない
- 共同編集機能によって変更履歴が機能していない
最近はオンライン上で共同編集可能なのが当たり前になってきましたが、これはバージョン管理という点では最悪な機能です。最早履歴は機能せず、記憶だけが頼りの高難易度間違い探しです。
ツールに付属の履歴機能をあてにしたバージョン管理はバージョン管理が存在しないのと同じです。
良いドキュメントとは何なのか
ここまでドキュメントの陳腐化の理由や実際にあった悪いドキュメントの例を紹介してきました。では「良いドキュメント」とは何なのでしょうか。
1. 更新が容易であること
前述したとおり、ドキュメントの更新コストの低さというのはそれだけでドキュメント更新のハードルを大きく下げます。
ドキュメントの更新でやりたいことは情報を最新のものに保つことであって、見た目を整えることではありません。ドキュメントの更新コストが低く、更新そのものに専念できるドキュメント（もしくはそのツール）は良いドキュメントと言えます。
2. 可読性が高いこと
これは見落としがちですが、ドキュメントは更新して終わりではありません。ドキュメントは読まれてはじめて意味を持つものです。
そして、ドキュメントは書く時間や人数よりも、読む時間や人数のほうが圧倒的に多くなります。「ドキュメントは未来の誰かが読むものである」ということは常に意識しておくべきです。
読みやすいドキュメントというのは、それだけで良いドキュメントと言えます。
3. 更新履歴に経緯が紐づいていること
これも見落としですが、ドキュメントというのは基本的に結論しか書かれおらず、そのようになった経緯というものはあまり残りません。
これは次にドキュメントを更新するときに困るケースがあります。たとえばある仕様を変更しようと思ったとき、なぜその仕様になったのかがわからないと変更してよいのかわからない、といった経験をしたことのある人は多いのではないでしょうか。
ドキュメントの本質からは外れますが、経緯が紐づいて残っているというのは後々効いてきます。
Markdown + GitHub + VitePressという選択肢
そこで、このような問題を解決しつつドキュメントの陳腐化を防止する手段の1つとして、Markdown + GitHub + VitePressという選択肢にたどり着きました。
フォーマットにMarkdownを採用した理由
今回、ドキュメントのフォーマットとしてMarkdownを採用しました。
1. gitとの相性が良い
この後に出てきますが、ドキュメント管理にはGitHubを採用氏ています。そのため、テキストベースであるgitとの相性が良いです。
仮に細かな変更があったとしても、 git diff を見れば何がどう変わったのかを容易に確認できます。
2. 書くことに専念できる
MarkdownはHTMLとCSSで言ったところのHTMLに当たるので、見た目を整えることに時間を取られることがありません、書くことに専念できます。
また、最近はドキュメントを印刷して読むということはほぼないに等しいです。ドキュメントというとWordのイメージですが、Wordは印刷を前提としたツールなので、改ページなど余計なものがついてきます。この辺りが地味にストレスになることがありました。
3. CIなどシステマチックに処理できる
Markdownはただのテキストファイルなので、textlintやPrettierなどを使ってフォーマットを整えたり、誤字脱字のチェックも行えます。
校正ツールがついた文書作成ツールもありますが、CIで横断的にチェックできるのは便利です。
管理方法にGitHubを採用した理由
また、ファイル自体はGitHubでgit管理することにしました。
1. Issue/Pull Request駆動で更新できる
コーディングをしているときに「なんでこうなったんだっけ」と過去のPull Requestのコメントを見返すことがあるでしょう。これがまさに「変更履歴と経緯が紐づいている」という状態になります。
ドキュメントも同じように「変更が必要になったらIssueを作成して議論し、Pull Request上でレビューしてMergeする」という方式を取ると、何も考えずとも履歴（commit）と経緯（IssueやPull Requestのコメント）が紐づいて残ります。
2. バージョン管理ができる
gitを使っているので当たり前ですが、バージョン管理もできます。commitやPull Requestを追えば、どのような変更があったのかを確認できます。
もしRelease Noteを作成しているのであればさらに変更履歴をまとめることもできます。
3. 従来の開発体験・フローを継承できる
これらの流れは普段プログラマーが行っていることとまったく同じです。
やはり普段から行っているフローと同じというのは導入も容易ですし、運用もしやすいです。
ツールにVitePressを採用した理由
そして書いたドキュメントをどのように公開するかというところで、VitePressを採用しました。
1. 運用コストがほとんどかからない
VitePressはMarkdownからSSGするツールであり、そのBuild結果はHTML/CSS/JavaScriptです。そのため、ホスティング先もGitHub PagesやS3 + Cloud Frontなど、ほぼ無料で運用できます。
2. 拡張性が高い
Markdownは基本的に文書を記述するためのものなので、UMLを書くことなどには適していません（画像にして埋め込むと差分がわかりにくくなる）。
しかし、VitePressはmarkdown-itを使ってMarkdownを拡張したり、Vue.jsのコンポーネントを使って拡張することができます。
こうしてMarkdownだけでは書けないようなドキュメントも扱うことが可能になります。
3. 必要最低限の機能が揃っている
とはいえ、VitePressには必要最低限の機能が元からある程度揃っています。以下はVitePressの機能の一部です。
- Algoliaを使った全文検索機能
- 最終更新日やGitHub Repositoryのリンク挿入
- 最近RAGを使ったAI Chat機能を搭載可能になった
これらがあるので、実際にドキュメントを読む場合に関しても、読みやすいドキュメントと言えます。
実際に運用してみて
この構成で運用してみた感想を以下にまとめます。
Markdown + GitHub + VitePressは相性がよかった
実際この3つの組み合わせは非常に相性が良かったです。
GitHub Pagesがプライベートにできないのでホスティングは別途方法を検討する必要はありますが、それ以外はすべてこの3つで完結させることができました。
すべてのドキュメントを扱うには難しい
とはいえ、すべてのドキュメントをこの方式で扱うのは難しいと感じました。
UMLであればmarkdown-it-plantumlを使えば書けますが、たとえばDBのテーブル定義書のような大きなテーブルを書くのは難しいです。この辺りは別のドキュメント管理方法を検討するか、そもそもドキュメントのフォーマット自体を見直す必要がありました。
完全に技術者思考
見ての通り、技術者にとっては使い慣れた環境ですが他の人からするとハードルは高いと思います。
閲覧だけであれば問題ないですが、議論に参加するにはIssueやPull Requestの概念を理解する必要がありますし、もしドキュメントを更新するとなるとgitの知識が必要になります。
まとめ
今回は今までの記事とは違って、ドキュメントの運用方法について書きました。ただ、最後のまとめでも書いた通りこれも完璧な方法というわけではありません。それぞれのチーム・プロダクトによってドキュメントの内容も異なるので、ドキュメントの運用方法も異なるはずです。
ひたすら読み物になってしまったので、よければイベントのアーカイブと合わせて読んでみてください。
Discussion