最近Design Docを書いている。25年の6月にDesign Docのフォーマットを本部で見直してチームとしてもここに書きまくろう！と決めたのだが、そこから我々のチームだけで6ヶ月くらいで50本くらい書いている*1
そうしてDesign Docを書いたり読んだりしていて、Design Docは読み手のことを考えて書く必要があるなと思うようになった。
- 結論は極力短くする
- 結論は早めに見せる
- 1つのDesign Docに1つのことを書く。多くなりそうだったら分割する
- 調査のときに書いたメモはDesign Docからリンクするようにして、Design Doc自体には書かない
- AIは書きまくるので、そのままコピペせずに必要な情報だけに添削する
- 書き手向けのテンプレート文言は消す
- 自分で「何も知らないフリ」をしながら読み返して添削する
まとめ
ドキュメントを書くのは、コードを書くのと同じだよね〜という話を同僚としていた。自分も完全に出来ている気はしないが気を付けてやりたいねという感じもコードと一緒ですね。
*1:とはいえ書いてる途中のものも多くある
