ドキュメントは書くべきか？
ドキュメントは書くべきだ、とわかっていても後回しになる。書いても誰も読まず、古くなって嘘になることもある。全部書くのも、何も書かないのも極端だ。
ドキュメントが負債になるとき
- 更新されず、現実とずれて、読むと逆に混乱する
- 書くこと自体が目的化し、誰も使わない資料が増える
- コードやコードの履歴を見ればわかることを、二重に書いている
ドキュメントが効くとき
- なぜその設計にしたか、という背景を残すとき
- 新しく入る人が、最初に迷う場所を先回りして説明するとき
- 自分が半年後に忘れる前提の、運用手順を書くとき
実用的な結論
書くべきは「変わりにくくて、思い出しにくいもの」だ。
- 意図や背景など、コードに残らない情報を優先して書く。
- 変わりやすい詳細は書きすぎない。古くなって嘘になるくらいなら書かない。
- 書いたら、置き場所と更新の担当を決める。放置される資料は最初から負債だ。
全部書くのではなく、未来の自分とチームが確実に困る箇所だけ書く。