こちらを読んで。うんうんそうだよなって共感しつつ、自分はもうちょっと意識が低くて
読む人のことを考える = 過去と未来の自分が読んでわかりやすい文章にする
ということを意識している。
※ドキュメント、の範囲が広いけど、Webエンジニアとして普段働く上で書いている社内文書やブログ記事などを指す。そこまでかっちりしてなくて、フォーマットが確立していない文書全般。
過去の自分に向けて書く
過去の自分に向けて書くというのは、端的に言うと
「その情報を知らなかった過去の自分が読んだときに、最短距離でキャッチアップできるような内容にする」
ということを意識している。
具体的にやっていること：
冒頭で「これは何について書かれたドキュメントか」を書く
社内向けのドキュメントを書くとき、自分はかなりの確率で冒頭に「これは何か」というセクションを設けるようにしている。
そこに、このページに書いてあることや、このページを書くに至った背景を簡単に記載している。
こうすることで、このページにたどり着いた人にとって読む価値のあるドキュメントか、をなるべく早く判断してもらえるといいなと思っている。
試行錯誤の過程をトレースするのではなく、目的を達成するために必要な情報だけを順番に並べる
特に技術調査系のドキュメント（XXをローカル環境に構築する手順、とか）だと、調査の過程でやったことをそのまま列挙してしまいがちになる。
そうではなくて、最終的に目的が果たせた後に、じゃあこの状態にたどり着くには結局何が必要だったんだっけ？を振り返ってそこに必要な情報だけを順番に書く。
「XXをXXしたらXXXというエラーが出たけど、XXXしたら解決できた」みたいな情報は回避できるのであれば初見の人にとってはノイズでしかないので、一通り書き終わった後にトラブルシューティングみたいな形で最後にまとめておく。
（割愛せずとりあえず残しておくのは、特にブログ記事とかだとそのエラーメッセージでググってたどり着く、みたいなケースを考慮して）
未来の自分に向けて書く
未来の自分に向けて書くというのは、端的に言うと
「その当時のコンテキストを思い出せる情報を残す」
「技術系のドキュメントであれば、再現可能な状態にしておく」
といったあたりが意識しているポイント。
未来の自分は過去の自分と違って、最低限「なんかそういう内容のドキュメントを昔書いたなー」ということは覚えている。
なので、構成について意識することはあまり変わらず、コンテキストをなるべく思い出せるようにしておく。
参考にした一次情報はリンクでたどれるようにする
社内ドキュメントであれば関係するGoogleドライブの資料とかSlackのやり取り、技術ブログであればそう考えた根拠となる公式ドキュメントや他人のブログ記事など、後から見返したときにも「何で自分はあのときそう判断したんだっけ」がわかるようにしておく。
なぜこのドキュメントを書いたのか、を残す
よく、「そこに書いてあることは理解できるが、何でこれを書くことになったのか思い出せない」みたいなシーンに遭遇する。
ので、こういう流れでこういう検討をすることになったんですよーっていうのを冒頭に残すようにしている。必須ではないけど。
技術系の話題であれば、ライブラリのバージョン情報とかも残しておく
あれ半年ぐらい前に調べたなーって言って自分のブログ読んでもっかいやったけどなんかうまく動かない、なぜならその間に言及してるライブラリのバージョンが上がって仕様が変わっているから、みたいなことも稀によくある。
なので、この記事を書いたときはこのバージョンだった、を残す。
---
こんな感じ。
毎回全部書いてるわけでもきっちり守れてるわけでもないけど、普段なんとなく意識していることを書いてみた。
余談だけど、昔尊敬する上司から「GitHubのリンク貼るときはmasterブランチじゃなくてtagを含むURLにしたほうがいい。masterブランチは常に更新されるので」って言われて、それは今も気をつけてる。