お仕事の話。
仕事で新チームに配属されたため、ドキュメント整備から始めている。
立ち上がってすぐのプロジェクトでは情報がどんどん更新されていくため、多少荒くても得た情報を網羅するようなドキュメントが求められている気がする。そうなると自然と短い単位のドキュメントが増えてくる。
それをやって気づいたのだが、タイトルが具体的で本文が短く端的に書かれていたほうが見やすい。あとから検索したときは特に。
例えば、Aというキーワードで検索したときに、検索結果に
- Aについて
- Aの仕様
- Aの問題点
というものが並ぶより
- AはBだ
- AはCかもしれない
- AはDの問題をかかえている
と表示されたほうが探しやすい。これは、FAQの書き方とかそういうものに近い気がする。
ある程度情報の更新が落ち着いて公式ドキュメントとして整理されるフェーズになったら、もっと構造化した文書を書くべきだとは思う。
それまでは書き捨てのメモを積み上げる感じで残していきたい。
