Google社のテクニカルライティングの基礎教育資料はよくまとまっており、とても有用です。
しかし、2点問題があります。
そこで、Technical Writing One・Technical Writing Twoを和訳・要約・再構成しました。
この記事の対象読者
-
日本語で技術文書を書く方
英文法に関する部分は省略しています。
英語で技術文書を書かないといけない方は、是非、原文を読んでください。
-
英文法の基本
-
単語のニュアンスの違いによる使い分け
-
句読点の使い方
を学ぶことができます。
-
和訳・要約
※以下の翻訳はGoogle翻訳をもとに著者が訳し、要約・再構成したものです。誤訳あれば訂正しますのでご指摘ください。
1：対象読者を決める
適切なドキュメント = 対象読者がタスクを実行するために必要な知識とスキル - 対象読者の現在の知識とスキル
適切なドキュメントであれば、上の関係が成り立つ。
よって、ドキュメントを書き始める前に対象読者を明確にする必要がある。
対象読者特定の手順
-
対象読者を、役割ごとに大まかに定義する
例: プログラマー
-
対象読者を細かく分類する
例: C++のプログラマーでvectorの応用的な使い方を知りたい人
-
対象読者にドキュメントの語彙・概念を合わせる
例：
分かる：クラス
分からない：クロージャ -
対象読者が学ぶものを決定する
ドキュメント作成時の注意点
ドキュメント作成時には以下の事に注意する。
-
過不足の無い説明をする
対象読者は作者が前提としている知識を持ち合わせていない可能性がある
2：ドキュメントの枠組みを構築する
以下のことに注意し、ドキュメントの枠組みを構築する。
- ドキュメントでカバーする範囲を明示する
- 対象読者・前提条件を明示する
- 重要なポイントを先頭に持ってくる
- ドキュメントの冒頭が、対象読者の疑問に答える形にする
- 長いドキュメントの場合、退屈・混乱させないエグゼクティブ・サマリーを用意する
- 対象読者のためになるような内容にする
- 各章別に論題を分ける
- 曖昧・不明確な説明になっていないか？
- リストは対象読者が目標を達するのに十分なステップ数であるか？
- システムのプロパティについての説明は十分か？
- 情報を段階的に開示する構成にする
- ドキュメントにナビゲーションとなるものを追加する
- ドキュメントが長大になる場合は、ドキュメントを分割することを検討する
3：段落を構成する
以下のことに注意し、段落を構成する。特に、段落最初の1文はその段落での論旨となるよう注意する。
-
段落最初の1文に注力する
- その段落での論旨をまとめる
- 読者は段落最初の1文だけ読んで、それ以降は読み飛ばすことがある
-
「1段落 = 1関心事」に抑える
-
段落は十分な長さにする
段落再検討の目安：
- 7文以上
- 大量の1文の段落
-
「なにを」、「なぜ」、「どのように」を明確にする
4：単語の使い方に注意する
単語の使い方に関する注意事項を以下にまとめる。用語と代名詞に分けて解説する。
用語
- ドキュメント内で一貫して使う
- なじみのない用語を使う場合、その用語を説明しているページがあればリンクする
- 略称を使う場合は初出のところで、「略さない用語(略称)」とする
- 以降、ドキュメント内ではその略称を一貫して使う
- なじみのない用語が多い場合は、定義を用語集にまとめる
代名詞
- 何を指しているのか明確にする
- 直後に名詞を置き、「この〇〇」または「その〇〇」とする
- 「指す語が離れている」もしくは「曖昧にとれる」場合は、あえて使わない
5：文章の構成に注意する
文章の構成に関する注意事項を以下にまとめる。
能動的な文章にする
- 「誰が」行うのか明確にする
- 受け身の文体にしない
明確な文章にする
-
単純な言葉を使う
重く、長々しい言葉は読者に受け入れられない
-
強い動詞を使う
弱い動詞の例：
- （偶然に）生じる
- （たまたま）起こる
-
具体的なデータで修飾する
技術文書はマーケティングでのスピーチではない
-
メタファに注意する
異なる文化圏では通じない恐れがある
-
場合によっては、説明のへのリンクではなく、チュートリアルへのリンクを張る
短い文章にする
-
「1文 = 1意」に抑える
長い文章はリストに変換する
-
無関係な単語を、排除または削減する
6：リストとテーブルの使い方に注意する
文章内でリストやテーブルを使う場合の注意事項を以下にまとめる。
共通
- リスト・テーブルについてのキャプションを付ける
リスト
-
リストアイテムを平行に保つ
- 文法
- 論理的なカテゴリ
- 大文字・小文字
- 句読点
-
番号付きリスト項目は命令形にする
-
アイテムを適切に区切る
テーブル
- リストより、比較・分析が容易である
- 各列に意味のあるヘッダーを書く
- 各列の内容を読者に推測させない
- セル内のテキスト量は適量にする
- テキストを入れすぎない
- 同じ列のデータは同一カテゴリの値とする
- 一つのセルだけ突飛な値とならないようにする
7：サンプルコードの構成に注意する
サンプルコードの構成に関する注意事項を以下にまとめる。
- 正確であること
- エラーなしでビルドできる
- 主張に沿ったタスクを実行する
- できるだけ実際の実装に沿う
- コードに脆弱性は含めない
- プログラミング言語固有の規則に従う
- 簡潔であること
- 理解容易であること
- 説明的なクラス、メソッド、変数名を使う
- 解読が難しいプログラミング技法等で読者を混乱させない
- 深くネストされたコードは避ける
- 例と反例を適切に使う
- 許可されない例を示すことも場合によっては有用である
- 適切なコメントが付与されていること
- コメントは簡潔・明快に付与する
- 明白なコードにコメントを書くことは避ける
- 直観的でないものに対するコメントに注力する
- 読者がその分野をよく理解している場合、「コードが何をしているか」ではなく、「なぜコードがそれを行っているのか」を説明する
- 再利用可能であること
- 依存関係やセットアップ方法など、コードを実行するために必要なすべての情報を示している
- コードは容易に拡張またはカスタマイズできる
- 複雑さ・難解さを段階的にあげる構成になっていること
8：イラストの構成に注意する
イラストの構成に関する注意事項を以下にまとめる。
-
イラストについてのキャプションを付ける
-
1つの図面の情報量を制限する
-
複雑な図は読者を圧倒する
-
複雑なシステムはサブシステムに分割して図示する
図：複雑なブロック図
↓
図：3つのサブシステムに編成された複雑なシステム
図：複雑なシステムの1つのサブシステムの詳細
-
-
注目する点を分かりやすくする
- 赤い円で囲むなど、視覚的な手がかりを追加する
- 吹き出しを追加する
9：推敲する
推敲する際は、以下のことに注意する。
- スタイルガイドを適用する
- 対象読者の立場で編集する
- 変更する箇所を、囲むなどして、明確にする
- 論題・章の構成を練り直す
- 曖昧・不明確な説明になっていないか？
- リストは対象読者が目標を達するのに十分なステップ数であるか？
- システムについてのプロパティの説明は十分か？
- イラストの内容がより明確に伝わるよう再検討する
- イラストで伝えたいことは何か？
- どうすればイラストを簡略化できるか？
- このイラストを2つ以上の単純なイラストに分割する必要があるか？
- イラストの文章は読みやすいか？
- イラストのテキストのコントラストは十分か？
- 書いたドキュメントを読み上げる
- 時間を置いて見直す
- 他の編集者にレビューしてもらう
元ページのコンテンツはCreative Commons Attribution 4.0 Licenseの下でライセンスされています。詳細については、Googleデベロッパーサイトのポリシーをご覧ください。
終わりに
Google社のテクニカルライティングの基礎教育資料をまとめ直しました。
より良い技術文書を書くためにお役立て下さい。
参考
Google社 Technical Writing Courses