開発におけるドキュメント運用の理想状態と課題

概要

開発におけるドキュメントの運用方法について、自分なりの理想状態についてまとめます。

簡単にまとめると以下の3つとなります。

1. ドキュメントが容易に見つかる
2. ドキュメントの正確性
3. ドキュメントの抜け漏れがないこと

上から順に実行難易度が下がり、容易に対策ができるはずで上から実行することを目指したいと思っています。
もっと項目を洗い出して整理はできると思いますが、一旦は上記を考えています。

それぞれの理想状態の項目についてと、それを実現するにあたり現状課題になりそうなポイントを整理します。

1. ドキュメントが容易に見つかる

• ドキュメントが書かれているが、歴史的な経緯でドキュメントの場所や管理システム自体がバラバラになったりする。
• 管理システムの移行が進まずに、古いドキュメントは過去に管理していたドキュメント管理システム上で残り続けてしまう。
• 結果としてメンバーによってドキュメントの場所がわからなかったり、コードや他のドキュメントでのリンク切れが起きる。

対策

• GitHubリポジトリのトップディレクトリのREADME.mdなど、リポジトリを最初に見た人が容易に見つけて辿れる状態にする 
  関連する全てのドキュメントはREADMEから容易に辿ることができる。
  リポジトリ外でドキュメント管理している場合でも、リンクを貼るだけでも効果があるため必ずやっておきたい。

• ドキュメントの階層の構造化
  ドキュメントの置き場所と階層が構造化され、どの機能・システムに関するドキュメントがどこに書かれているか場所が推測できること
  また、その構造化についての情報も開発者のREADMEにまとまっていること
  これにより、近い将来LLMを使ったシステムでドキュメントを扱いやすい状態にし、chatbotなどで聞けば答えれるようにして、そもそもドキュメントを探さない状態に持っていく

2. ドキュメントの正確性

どこで書くか、どういう粒度で決まっており、特定のトピックに関しては特定のドキュメントで運用し続ける状態を目指す。
これが整っていると、メンバーによって同じ内容を別々の場所で書いてしまったり、内容の重複を防ぎ、運用がより回ると考えています。

対策

• ドキュメントを書く粒度やテンプレートなどが定まっていること
• ドキュメントの変更履歴がわかるシステム上で管理すること
  • そのリポジトリに関するシステムなら極力リポジトリ内に寄せる.

3. ドキュメントの抜け漏れがないこと

開発案件の大小や、その時の開発チームのメンバーのタスク量によって、ドキュメントを書く・書かないがぶれてしまうことがある

対策

• そもそも設計・開発においてドキュメントドリブンでの開発体制を敷く
  • 開発担当者個人の頭の中で設計をするのでなく、まずドキュメントにまとめて叩き台を作り、それに対して周りのメンバーのレビューを実施する
    • これによって設計の抜け漏れをなくす。
    • また、メンバー間でのシステム設計の理解度を揃えることができる。

ドキュメント運用上の課題

前述した運用体制を敷いた際に、個人的に運用上の課題になりそうなポイントがいくつかあるので、それについての課題を整理します。

リポジトリを跨いだ大きなシステムの全体構成・設計について

複数リポジトリにまたがるシステムに関するドキュメントはの運用をどうするか
あくまでGitHub内にとどめるなら、該当のGitHub org内にドキュメント用のリポジトリをまとめ、そこで管理するのが良いのか

システムに関する変遷について

開発初期から、アーキテクチャ変更など、途中段階も含めた一連のストーリーを理解する資料があると良さそう
GitHubリポジトリなどではコミットログなどから変更履歴はたどれるが一連の変遷を理解できるようにするとシステムの理解につながると思う。
-> システム上の意思決定の変更についてはArchitectural Decision Records(ADRs)での運用が最適?

さいごに

ドキュメントについて個人的な理想状態と課題を整理しました。

開発においてドキュメントが容易に見つかり、それらのドキュメントが常に正しい内容を維持しており、抜け漏れがない仕組み・体制を作れれば、開発メンバーのキャッチアップが容易になり、開発における心理的不安や、ドキュメント駆動でシステムの設計・開発品質向上のためのメンバー間でのコミュニケーション活発化を目指せるはずです。

チームのメンバーでそれぞれ理想状態と運用コストに関する考え方も異なるので、度々メンバー間で話して、運用方法をブラッシュアップできればと思います。