口伝の奥義書
「仕様に関しては、田中さんに聞いてください」。
ドキュメントが存在せず、全ての知識が「特定の個人の頭の中」だけにあります。
その田中さんがインフルエンザで休んだら？転職したら？
プロジェクトは即座に停止し、残されたメンバーは誰も読めない古文書（ソースコード）の解読を強いられます。
- 「README.txt」が空白、または「TODO」と書かれている
- 仕様変更が口頭やチャットで伝えられ、どこにも記録されない
- 新人が入っても、セットアップに1週間かかり、先輩がつきっきりになる
- 「あの機能どうなってる？」と聞ける人が、チームに一人しかいない
その1人がバスに轢かれたら、プロジェクトは終了です。
01. ドキュメントは「手紙」である
ドキュメントを書くことは、未来の自分や、まだ見ぬ同僚への「手紙」を書くことです。
「なぜこの設計にしたのか？」「なぜこのライブラリを選んだのか？」。
コードは「How」しか語りません。
ドキュメント（コメントやADR）だけが、隠された「Why」を語ることができます。
記録は残る。
02. ドキュメント・アズ・コード
「Wikiはすぐに古くなる」という言い訳はもう終わりにしましょう。
Markdownで書き、Gitで管理し、CIで自動生成する（Docs as Code）。
コードの修正プルリクエストに、ドキュメントの修正が含まれていなければマージしない。
これをルール化すれば、ドキュメントは常に最新に保たれます。
03. オンボーディングの自動化
優れたドキュメントがあれば、新人は「これ読んでおいて」の一言で戦力化できます。
環境構築手順書（あるいはコンテナ化）が完璧なら、初日でコードが書けます。
ドキュメントへの投資は、教育コストの劇的な削減となって返ってきます。