開発におけるドキュメントの運用方法について、自分なりの理想状態についてまとめます。簡単にまとめると以下の3つとなります。ドキュメントが容易に見つかるドキュメントの正確性ドキュメントの抜け漏れがないこと上から順に実行難易度が下がり、容易に対策ができるはずで上から実行することを目指したいと思っています。項目を洗い出して整理はできると思いますが、一旦は上記を考えています。それぞれの理想状態の項目についてと、それを実現するにあたり現状課題になりそうなポイントを整理します。ドキュメントが容易に見つかるドキュメントが書かれているが、歴史的な経緯でドキュメントの場所や管理システム自体がバラバラになったりする。管理システムの移行が進まずに、古いドキュメントは過去に管理していたドキュメント管理システム上で残り続けてしまう。結果としてメンバーによってドキュメントの場所がわからなかったり、コードや他のドキュメントでのリンク切れが起きる。対策GitHubリポジトリのトップディレクトリのREADME.mdなど、リポジトリを最初に見た人が容易に見つけて辿れる状態にする関連する全てのドキュメントはREADMEから容易に辿ることができる。リポジトリ外でドキュメント管理している場合でも、リンクを貼るだけでも効果があるため必ずやっておきたい。ドキュメントの正確性どこで書くか、どういう粒度で決まっており、特定のトピックに関しては特定のドキュメントで運用し続ける状態を目指す。これが整っていると、メンバーによって同じ内容を別々の場所で書いてしまったり、内容の重複を防ぎ、運用がより回ると考えています。ドキュメントの抜け漏れがないこと開発案件の大小や、その時の開発チームのメンバーのタスク量によって、ドキュメントを書く・書かないがぶれてしまうことがある対策そもそも設計・開発においてドキュメントドリブンでの開発体制を敷く開発担当者個人の頭の中で設計をするのでなく、まずドキュメントにまとめて叩き台を作り、それに対して周りのメンバーのレビューを実施するこれによって設計の抜け漏れをなくす。メンバー間でのシステム設計の理解度を揃えることができる。前述した運用体制を敷いた際に、個人的に運用上の課題になりそうなポイントがいくつかあるので、それについての課題を整理します。org内にドキュメント用のリポジトリをまとめ、そこで管理するのが良いのかシステムに関する変遷について開発初期から、アーキテクチャ変更など、途中段階も含めた一連のストーリーを理解する資料があると良さそうGitHubリポジトリなどではコミットログなどから変更履歴はたどれるが一連の変遷を理解できるようにするとシステムの理解につながると思う。Records(ADRs)での運用が最適?さいごにドキュメントについて個人的な理想状態と課題を整理しました。ためのメンバー間でのコミュニケーション活発化を目指せるはずです。チームのメンバーでそれぞれ理想状態と運用コストに関する考え方も異なるので、度々メンバー間で話して、運用方法をブラッシュアップできればと思います。2019の17日目の記事となります。優れた技術専門職になるためのガイド」の内容レビューに関わらせていただきました。4はてなブログをはじめよう!kaktsさんは、はてなブログを使っています。ブログを報告する引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。