6. まとめ

『テクニカルライティング Two』ではテクニカルライティングに関する次の中級者向けの事項を説明しました:

• スタイルガイドを採用する。
• 読者のように考える。
• ドキュメントを (自分に向かって) 声に出して読む。
• 原稿を書き終えたら時間をおいて読み直す。
• 優れたピア編集者を見つける。
• ドキュメントのアウトラインを作る。もしくは自由に書いてから構成を考える。
• ドキュメントの目的と前提知識を述べる。
• タスクの言葉を使った見出しを選ぶ。
• (適切なら) 情報を段階的に示す。
• 図を作る前にキャプションを書く。
• 一つの図に含まれる情報量を制限する。
• 図を見て理解すべきことをキャプションに書いたり、図に視覚的な手掛かりを書き入れることで、読者の注意を重要な部分に向かわせる。
• 理解しやすい簡潔なサンプルコードを書く。
• コメントは短くする。ただし、短さよりは明確さを優先する。
• 明らかのコードにはコメントを付けない。
• コメントはコードの直感的でない部分に集中させる。
• 望ましい例だけではなく望ましくない例も示す。
• 様々な複雑さを持ったサンプルコードを示す。
• 何度も推敲するのを習慣とする。
• 異なるユーザーのカテゴリに対する異なるドキュメントを提供する。
• 読者が知っていることと説明していることを比較し、違いを説明する。
• チュートリアルでは、概念の説明を例で補強する。
• チュートリアルでは、読者が遭遇する可能性のある問題を記しておく。

時間が許す限り、テクニカルライティングの追加リソースにも目を通してみてください。