アキレス腱を切ってしまい、入院している@moc_yutoです。
今回はフォーマットがバラバラになりやすいドキュメントに関して書きます。
ドキュメントとは
ドキュメントは非同期で知識を共有するための大切なツールです。 引き継ぎ、新メンバーなど知識共有の効率をあげるための必需品です。
エンジニア界隈だけでなく企業で仕事をしている場合であれば、必ずと言っていいほどドキュメントは書くでしょう。
その際、両者にとって不幸にならないドキュメントとはどういうものでしょうか？ 自分が書いている場合のドキュメントのフォーマットをまとめます。
自分が主にドキュメントに書く内容は以下3点です。
- 背景
- 目的
- 詳細
内容について
背景
ドキュメントにおいて、一番重要だと思っています。 作業手順でない限り、基本的には必ず背景をいれています。
たとえば、画面の表示制御のためのフラグを単独で別テーブルで管理している場合があります。 コードやDBスキーマを読むだけでは、わざわざ別テーブルにしてる理由がわかりません。 しかしここで背景を書いておけば、そのフラグは一時的なもので一定期間でそのフラグを消すため、変更しやすいように別テーブルに置いている。などと分かります。
目的
これも背景に近いですが、ドキュメントを書いているのであれば、何かを説明しているはずです。
その説明するものは何のためにドキュメントに残しているのか、どうしてこれが必要なのか目的を書くべきです。
詳細
この部分はドキュメントを書くとなったら誰でも書くと思うので、特に留意する点はないかな。 長い文章にするのではなく、簡潔にするくらい。 ここに関しては、コードで補えることも多いので、ドキュメント自体のメンテ性を落とさないようにするために書きすぎないことでしょうか。
その他
章立てはなるべく細かくして、知りたい内容に関して見出しに行けば分かるようにします。
そして、読む人のこともしっかり考えるということも重要です。 読む人はこのドキュメントに何を期待しているんだろうと一瞬でも考えるとそのドキュメントの質はかなり上がるはずです。
まとめ
基本的にコードを読んで分かるというのは挙動だけであって、なんでそういう実装をしたのかはコードのコメントにちゃんと書いてないと分かりません。 ただコードを読むのにも、ある程度負担はかかるし、その概略を自然言語で読めるのであれば、そのほうがいいに越したことはありません。
ドキュメントは詳細に書きすぎなくてもいいが、要点はしっかり書いておくべきです。
