「読む人のことを考える」
これだけ。
僕は、ドキュメントを読むのが苦手。すぐに混乱する。
ひとつの段落が長いと混乱する。正確に書いてくれているんだろうけど、書き手目線で細かくばーって書いてあって、読み手がそこから自分の目的の情報を探し出さないといけない状態だと混乱する。
あと、ページの階層が深かったり、リンクでジャンプしまくったり、用語がぶれていたり、文章が複数の意味に捉えられる書き方になっていたりすると、混乱する。
他にも、このあたりに気をつけてる
- いきなり詳細の話から始まると混乱するので、全体を説明してから詳細に入るように書く
- 段落は長いと読めないので、3〜5行にする
- 違う意味にとられないように気をつける（赤いシャツのシミ、は、シャツの赤いシミ、ともとれるから、シミが赤いシャツについている、って書くとかそういうの）
- 受動態だと主語が分かりにくいので、能動態にできないかを考える
- 二重否定を避けられないか考える
- 複雑な説明は、文章だけじゃなくて、図を描く
- ページ階層が深くなりすぎないようにする
- リンクは文章中よりも、参照リンクの項目にまとめたほうがいいかどうかを考える
- 同じことをできるだけシンプルに書けないかを考える
- ここに書かなくてもいい情報を書いてしまわないように気をつける
とか、そういう風にして、自分が読んでも混乱しないドキュメントにしてる。