ドキュメント作成のポイントまとめ

仕事でドキュメント（画面仕様書）を作成し、上司にレビューしてもらった際にいただいた指摘事項を「ドキュメント作成のポイント」としてまとめてみます。
個人的に重要だと感じた部分については、太字にしています。

1.＜ドキュメント作成全般のポイント＞

・何について、誰に対して説明するのか、コンセプトを決めてから作成する
・全体の構成を考えるため、まず目次を書いてから内容に着手する
・ドキュメント全体を通して「文章」になるようにする
・良いドキュメントとは、理解するために何度も読み返す必要がないものや読み返すのに時間がかからないもの
・目次を書く → 内容を書く → 見直し、のようにルールを作って作成する
・更新履歴をちゃんと残す
・目次の各項目には番号を振る
・手段と目的が入れ替わらないようにする

2.＜文章表現のポイント＞

・「～を確認する」などの曖昧な言い回しは使わない（読み手によって解釈が変わるような書き方はしない）
・「画面概要説明」のような無理やり名詞を連ねた表現はしない（ミスリードを起こす可能性がある）
・強調したい部分は太字にする
・配色には注意すること（赤は発色が強くて乱用すると目が痛い）

3.＜画面仕様書のポイント＞

・画面の目的の説明はドキュメントの一番最初に行う（ここをしっかり書かないと後続の内容が曖昧になりやすい）
・概要の説明では箇条書きを極力行わない
・ページタイトルを書く（呼称するときに困るため）
・各ページで何を説明するのかを常に意識する
・画面レイアウトの説明は 1ページで終わらせるのではなく、必要に応じてレイアウトをパーツごとに切り出し、各パーツ専用のページを用意して説明する
・画面レイアウトの各パーツに振った番号は、ドキュメント全体で紐づくようにする
・画面レイアウトはページ内で左寄せし、各パーツの説明は右寄せで書く
・一覧表を作成する場合、余白はできるだけ少なくなるようにする