「読む人のことを考える」
これだけ。
僕は、ドキュメントを読むのが苦手。すぐに混乱する。
ひとつの段落が長いと混乱する。正確に書いてくれているんだろうけど、書き手目線で細かくばーって書いてあって、読み手がそこから自分の目的の情報を探し出さないといけない状態だと混乱する。
あと、ページの階層が深かったり、リンクでジャンプしまくったり、用語がぶれていたり、文章が複数の意味に捉えられる書き方になっていたりすると、混乱する。
そんな風に、たぶん僕は他の人よりもドキュメントを読むのが苦手なんだと思う。
だから、自分が読んでも混乱しないようなドキュメントを書くと、まわりの人にとっても分かりやすいドキュメントになっているみたい。それで「分かりやすいね」って、ほめてもらって嬉しい。ドキュメントを読むのが苦手で役に立った！
どんなことに気をつけてるかな？と考えてみる。
そのドキュメントの目的が分からないと混乱するので
誰がどういう立場で読むのか
何を知りたくて読むのか
を考える。それに合わせて、目的をしぼる。
この前、ある機能に対するドキュメントを、PdMが読んで更新する仕様まわりのものと、エンジニアが知りたい実装まわりのものと、運用するときに必要になる注意点などに分けたら、チームメイトに「分かりやすいね」って言ってもらえた。
他にも、このあたりに気をつけてる
いきなり詳細の話から始まると混乱するので、全体を説明してから詳細に入るように書く
段落は長いと読めないので、3〜5行にする
違う意味にとられないように気をつける（赤いシャツのシミ、は、シャツの赤いシミ、ともとれるから、シミが赤いシャツについている、って書くとかそういうの）
受動態だと主語が分かりにくいので、能動態にできないかを考える
二重否定を避けられないか考える
複雑な説明は、文章だけじゃなくて、図を描く
ページ階層が深くなりすぎないようにする
リンクは文章中よりも、参照リンクの項目にまとめたほうがいいかどうかを考える
同じことをできるだけシンプルに書けないかを考える
ここに書かなくてもいい情報を書いてしまわないように気をつける
とか、そういう風にして、自分が読んでも混乱しないドキュメントにしてる。
これは、ほんとうに同意しかない。
ドキュメントを書くときには、書いている自分の目線ではなく、そのドキュメントを読んでいる人の目線で書きたい。
書き手としては、これも書いておきたい、あれも書いておいたほうがいいかもってなってしまうけど、そのドキュメントを読んでいる人にとって必要な情報にしぼって書くほうが、読みやすい。
書くときに多少手間がかかっても、ドキュメントは読まれることの方が多いので、書きやすさよりも、読みやすさのほうが大切だなーと思っている。
そのドキュメントを書いている僕も、数ヶ月もすれば書いたときのことをほとんど忘れて読み手になっているからね。コードもそうだね。
だから、ドキュメントを書くときには、読む人のことを考えて書いている。