わかりやすい

短い

用語の一貫性を保つ

曖昧な代名詞を避ける

受動態より能動態を使う

強い動詞を使う

曖昧な動詞よりも意味が限定される動詞を選ぶ

冗長な語は取り除く

段落の骨子を示す良いリード文を作る

長い文章は箇条書きにする

言葉の並列性を保つ

順序が重要でなければ番号のない箇条書きを使う

順序が重要なら番号付き箇条書きを使う

番号付き箇条書きは命令語で始める

ドキュメントの最初に明確な要約を示す

テンプレート化する

対象読者を想定する

読者の前提知識を定義する

ドキュメントの対象範囲と前提条件を最初に示す

読者がすでによく知っているものと比較する

ユーザーによってそれぞれ異なる資料形態を提供する

複数の例を見せる

読者がつまづきやすい点を指摘する

確認する

書いたものを声に出して読んでみる

下書きは少し寝かせてまた読んでみる

継続的に見直す

ドキュメントのアウトラインを作る

書く前 or 書いた後

できるだけタスクベースの見出しにする

新しい情報は小出しにする

新しい概念・指示など

作成する前に、説明書きを書いてみる

1つの図面内の情報量を制限する

適切な箇所に読者の注意を向ける

キャプションで要点を説明する

注意を惹くマークを追加する

簡潔なサンプルコードを作成する

良い例だけでなく、良くない例も提供する

複数の複雑さを想定したものを提供する

短くするが、簡潔さよりも明快さを優先する

自明なコードには書かず、直感的でない部分を明らかにすることに集中させる