広告
テクニカルライティングの必要性
相手に必要な情報を伝えるための文章には工夫が必要ですよね。僕は人に情報を伝えることが苦手なので「テクニカルライティング」は、非常に重要な技術だと考えます。
「テクニカルライティング技術」を持っている人は尊敬します。
専門的な技術についての情報を伝えることは難しいことだと思います。しかしながら専門性の高い技術を取り扱う技術者は、能力が高い人ほど傲慢になりがちです。独りよがりで読み手を意識していない文章になりがちだと思います。
テクニカルライティングのチェックリスト
たとえば、「Googleのテクニカルライティングの原理原則」では、下記のような要点の学習コースを準備しています。
これは、学生向けのコンテンツなので基礎的な内容とされていますが、
- 表記の揺れを起こさないように用語を使ってください。
- 曖昧な代名詞は避けてください。
- 受動表現より能動表現を使ってください。
- 曖昧な動詞よりも特定の動詞を使ってください。
- 各文を1つの要点に集中させてください。
- （必要に応じて）いくつかの長い文章をリストに変換してください。
- 不要な言葉を排除してください。
- 順序が重要な場合は番号付きリストを使用し、順序が重要でない場合は箇条書きを使用します。
- リストアイテムを平行に保ちます。
- 番号の付いたリストアイテムを命令語で始めます。
- リストとテーブルを適切に使ってください。
- 段落の中心点を確立する優れた冒頭文を作成します。
- 各段落を1つのトピックに焦点を当てます。
- 読者が学ぶ必要があるものを決定します。
- ドキュメントを読者の理解度にあわせてください。
- ドキュメントの最初にドキュメントの重要なポイントを明記してください。
- スタイルガイド、標準化に従ってください。
- 読者は誰かを考えてください。
- 文書を（自分自身に）大声で読み上げます。
- 下書きを書いた後は、ドキュメントに戻ってください。
- 優れたエディタを見つけてください。
- ドキュメントの概要を説明します。または、自由形式で書いてから整理します。
- ドキュメントのスコープと前提条件を紹介します。
- タスクベースの見出しを優先します。
- 情報を段階的に開示する（状況によっては）。
- イラストを作成する前に、キャプションを書くことを検討してください。
- 1つの図面内の情報量を制限します。
- キャプションで要点を説明するか、画像に視覚的な合図を追加することにより、画像または図の関連部分に読者の注意を向けます。
- 理解しやすい簡潔なサンプルコードを作成します。
- コードのコメントは短くしますが、簡潔さよりも明快さを優先します。
- 明白なコードに関するコメントを書くことは避けてください。
- コード内の直感的でないものにコメントのエネルギーを集中させます。
- 例だけでなく、反例も提供してください。
- 複雑さの範囲を示すコードサンプルを提供します。
- 継続的な見直しの練習をしてください。
- ユーザーのカテゴリごとに異なるドキュメントタイプを提供します。
- 読者がすでに知っているものと比較してください。
- チュートリアルでは、例を使用して概念を強化します。
- チュートリアルでは、読者が遭遇する可能性のある問題に注意してください。
さいごに
どのチェックポイント大切にしたいですね。
読み手の理解度や知りたいことを意識すること
丁寧に十分に推敲を繰り返すこと
といったところなのかな。
簡単な話ではないですね。
