この1年ぐらいは特に最初にドキュメントを書く。と言うことを重視している。開発時の新機能の設計などもそうだし、こういう施策をやります。というのも残してメンテナンスするようにしている。
開発の文脈においては、自分が何を考えてこの設計にしているのか、ここは切り捨てたのか。という。自分の考えを整理するのが第一の理由。この機能の目的やどういう機能があるかを含めて、全体を俯瞰した図だったり、コードだけでは伝わらない情報を記載する。ただ、ここは後でコードやコードのコメントに書く予定のところも書くこともある。実装する前にこの辺で一度他の人に設計のレビューをしてもらう。
実際に実装するときは、ドキュメントからコードやコードコメントに書く予定のところは削除する。面倒くさいように見えるが、同じ物を2カ所書く意味はなく、コードが正であるため。機能の全体図や設計意図だけが残ったドキュメントと、その意図を反映したコードができる。(はず)
開発以外の文脈においては、なぜこの施策をやるのか？目的や意図、もしあるのであればこうやってほしいという手順や気をつけるポイントなどを書く。さらっと口頭でやればいいじゃないという意見もあるかもしれないけど、後から読み直したり、後から入ってくる人もいる。後から入ってくる人がうまくオンボードできるにはこういうドキュメントをちゃんと書くというのが大切だと思っている。
これは組織の設計とソフトウエアの設計が似てると考えているところがあって、もし自分がいなくなっても回るように意図を残すと言うところを意識してる。 ~~あと自分が都度説明するのもぶっちゃけ面倒だし~~
もちろんドキュメントはちゃんとメンテナンスする。メンテナンスされていないドキュメントなら無いほうがマシだし...今使われていないドキュメントならば、アーカイブ機能が無ければ削除してしまってもよいぐらい。