ドキュメントが必要というのは誰もが思っていることだと思うけど、わかりやすくて過不足の無いドキュメントを書くのは難しい。自分が実装したり構築したりするシステムのドキュメントを書くとき、最近は3種類の人に対して別々の文書を用意するように努力している。

ユーザ向け

どうやって使うのか、どうやって接続するのか、各エンドポイントがどんな意味を持っていてどんなリクエストを受け付けるのか、等々。他のドキュメントと比べてこれが一番対象読者の数が多いので必ず書くようにしているんだけど、自分自身がユーザじゃないことが多くてどの情報が必要なのか正しく判断できず、過不足があることも多いのが悩ましい……

運用者向け

どうやってセットアップするのか、どのサーバで動いているのか、他のどのサービスに依存しているのか、等々。僕の場合、自分が運用者になることも多く自分自身が対象読者に含まれているので、そのときにどんな情報が欲しいか想像しやすくてこの種類のドキュメントは書きやすい。僕が書いたドキュメントに対して他の運用者が実際わかりやすいと思ってるのかどうかは知らないけど……

開発者向け

そのシステムを手元で動かすにはどうするのか、どういうポリシーでこの設計になっているのか、等々。これも自分自身が対象読者に含まれているドキュメントではあるんだけど、運用者向けドキュメントと比べて何を明文化すべきなのかよく分からなくて、あまり書けていない……

ここで挙げた3つは完全に独立しているわけではなくて、例えば用語集とかログの場所とかは全員知っておいたほうがよさそうだし、全体的な構成は運用者も開発者も知っておいたほうがよさそうだったりする。とはいえこういう区分でドキュメントを分けるのは個人的にはうまくいっていると思っていて、今後もこの3つの分類を意識していこうと思っている。