Googleのテクニカルライティング教材から学ぶ：要点とやりがちなミス
概要
技術文書を書く際に、「伝わりやすい文章」を意識することは重要です。そのための指針として、筆者が技術文書を書く際に参考にしているのが、Googleのテクニカルライティング教材[1]です。Web上で無料で公開されており、技術文書を分かりやすく書くためのポイントが学べます。
本記事では、Googleのテクニカルライティング教材を基に、筆者が技術記事を書く中でやりがちなミスとともに要点を解説します。
今回は、以下の2点を紹介します：
- 能動態を使う（主語を明確にする）
- 対象読者を明確にする
対象読者
- 技術文書を書いている人、これから書きたい人
- テクニカルライティングを要点に絞って知りたい人
- よくあるミスの具体例と改善方法を知りたい人
- Googleのテクニカルライティング教材（英語）を、日本語で要約して読みたい人
注）日本語で読みたいだけなら、Googleのテクニカルライティング教材を日本語訳している記事もあります（本記事の最後に関連リンクを載せています）
この記事で書かないこと
- 本記事では、Googleのテクニカルライティング教材の全内容を説明するのではなく、筆者が特に重要だと考える点に絞って解説します。
注）網羅的な説明を知りたい方は、教材の原文や他の解説記事（本記事の最後に関連リンクを掲載）をご参照ください。
テクニカルライティングでここを気を付けよう～筆者のあるあるまとめ～
筆者が実際に技術記事を書く中で課題に感じた順に説明していきます。
対象読者を明確にする
Googleのテクニカルライティング教材のAudienceの内容です。
要約
技術文書を書く際には、読者を明確にすることが重要です。最低限、以下の点を考慮しましょう：
- 対象読者のロール
- 対象読者の前提知識
- 対象読者の目的
ちなみに、筆者は技術文書を書くときに「対象読者を必ず書く」という自分ルールを決めています。補足すると、以下の問いを考えるようにしています：
- これから書く技術文書が、対象読者に提供する価値はなにか？
つぎに、筆者の過去記事のミスを基に、もう少し深掘りしていきましょう。
例1：対象読者を考えていない
1つ目は、「OSSのデザインパターン解説シリーズ：Iteratorパターンの活用と悪いコード例」です。
単純に、対象読者が書かれていません（この記事は筆者が最初に書いた記事で、対象読者のことは考えていませんでした）。
今回の修正方法は、次の通り対象読者を明記することです：
対象読者
- デザインパターンを勉強したが、具体的な使用例を知りたい人
- デザインパターンが使わない場合のコード例とデメリットを知りたい人
対象読者が明確になりました。対象読者を冒頭に書くことで、以下のメリットがあります：
- 読者は、対象読者を見て、技術文書の内容と読者の目的が適しているかわかる（適していなければ、そこで読むのをやめることができる）
- 筆者は、対象読者を明確にすることで、より読者に適した文章を書ける
2つ目の筆者に対するメリットに関して、対象読者を踏まえると以下のような点で元の記事を直すことができるでしょう：
- 「デザインパターンを勉強した」という前提 => 記事の中で「Iteratorパターンとは？」の説明を省略してもよい
- 「具体例を知りたい」という前提 => 記事の中で、コード例を多めに掲載するようにする
- 「デメリットを知りたい」という前提 => 記事の中で、デザインパターンのメリット/デメリットの表を入れる
例2：本記事の対象読者
2つ目の例として、本記事でも対象読者を明記しています。再掲になりますが、以下を対象読者としています。
対象読者
- 技術文書を書いている人、これから書きたい人
- テクニカルライティングを要点に絞って知りたい人
- よくあるミスの具体例とともに学びたい人
- Googleのテクニカルライティング教材（英語）ではなく、日本語で読みたい人
筆者は、上記の対象読者を踏まえて、例えば以下の点を気を付けて本記事を執筆しました：
- テクニカルライティングを要点に絞って紹介する
- 失敗例の具体例を多めに入れる
また、技術記事の場合、他の記事との差別化も大切です。対象読者を明確にすることで、「他の記事との差別化」も同時に考慮できます。
（補足）本記事では「この記事で書かないこと」（≒対象読者でない人）も記載しました。「対象読者」だけでは不明確な場合は、「対象読者でない人」も書くことで、読者とのミスマッチを防義やすいと考えています。
能動態を使う（主語を明確にする）
Googleのテクニカルライティング教材のActive voice vs. passive voiceの内容です。
要約
技術文書では能動態を使う（受動態は避ける）ことが大切です。能動態を使う理由は、能動態は主語が明確で、読者にとって読みやすいからです。逆に、主語を省略したり受動態を多用したりすると、読者にとって読みにくく、誤解を与える文章になってしまいます。
さらに、能動態を使うことが大切である理由は、英語に比べて日本語は主語が省略されがちだからです。より強調するなら、日本語文書においては、主語が明確な能動態を使うことが大切だと考えています。
日本語では、主語に限らず色々な単語が省略されがちだと思います。主語に限らず目的語ー登場人物やモノ（誰が・誰に・誰の・何に...）ーを明示するとよいと思います。
つぎに筆者の過去記事のミスを紹介します。
例1：複数の登場人物と受動態
1つ目は、「RDBにおける、共有ロック/占有ロック・2相ロック・トランザクション分離レベルの関係をシーケンスで説明する」の以下の記載です（今回は意図的に気を付けた例です）：
READ UNCOMMITEDで考えた例と同じ状況を考えてみる：
- Aさんの口座残高の初期値が500円
- Aさんは100円を預け入れしたい
- Bさんは100円を送金したい
データベースのロックを説明するために、銀行口座の例を説明した箇所です。AさんとBさん（主語）が明確で誤解を与えにくい文章だと思います。
一方で、初めに書こうとしていたのは、以下の文章です：
READ UNCOMMITEDで考えた例と同じ状況を考えてみる：
- 口座残高の初期値が500円
- 100円を預け入れする
- 100円が送金される
これを読んだ読者は、例えば、以下のように考えるかもしれません（読者は太字部分を頭の中で変換しながら読んでいます）：
READ UNCOMMITEDで考えた例と同じ状況を考えてみる：
- 誰かの口座残高の初期値が500円
- 口座の持ち主が100円を預け入れする
- 別の誰かが100円を送金する
が送金される
頭の中で変換しながら読むことは、読者にとって負担であり読みにくいですし、場合によっては誤解を与えてしまいます。それを防ぐために、初めの文章のように主語を明確にした能動態を使うことが大切です。
例2：手順の説明には命令形を使う
2つ目は、「ECS (EC2起動タイプ) が永遠に起動しない場合の対処法 #初心者」の以下の記載です：
私は、こちらの方法で、今回の事象を回避しました。
- 「ECS > タスク定義 > インフラストラクチャの要件 > タスクサイズ」でCPUとメモリを小さくする
- 「ECS > タスク定義 > コンテナ > リソース割り当て制限 - (条件付き)」でCPUとメモリを小さくする
上記は、ECS関連のトラブルシューティングの手順を記載しています。こちらも主語が省略されています。
この場合は、（少し微妙ですが）主語は筆者です。しかし、もう少し考える必要があります。
この記事の目的（≒対象読者）は「読者がトラブルシューティングをすること」です。つまり、上記はトラブルシューティングのための手順であり、主語は読者として記載したほうが適切です。
したがって、以下のように書き直すことができます：
今回の事象を回避するには、以下の手順に従ってください：
- 「ECS > タスク定義 > インフラストラクチャの要件 > タスクサイズ」でCPUとメモリを小さく設定してください。
- 「ECS > タスク定義 > コンテナ > リソース割り当て制限 - (条件付き)」でCPUとメモリを小さく設定してください。
命令形を使うことで主語が読者であることが明確になり、読者にとって理解しやすい文章になります。
（補足）Googleのテクニカルライティング教材では、以下のように命令形の主語はあなた（読者）である。命令形は能動態であると説明しています。
Sentences that start with an imperative verb are typically in active voice, even though they don't explicitly mention an actor. Instead, sentences that start with an imperative verb imply an actor. The implied actor is you.
まとめ
以下の2点に絞って、テクニカルライティングのポイントを紹介しました：
- 能動態を使う（主語を明確にする）
- 対象読者を明確にする
上記の2点は、筆者が特に重要だと考えるポイントです。技術文書は、読者が明確に理解できることが何より大切です。そのために「能動態を使って主語を明確にする」「対象読者を意識して書く」ことを意識すると、より伝わりやすい文章になります。
Googleのテクニカルライティング教材では、上記の2点を含めた様々なポイントが紹介されています。より詳細を知りたい方は、Googleのテクニカルライティング教材を参照してください。
関連リンク
- Google 「Technical Writing」（Googleのテクニカルライティング教材） - Googleが無料で公開している技術ライティングの学習教材。
- Google社のテクニカルライティングの基礎教育資料を和訳・要約した - Google 「Technical Writing」の紹介ブログ
- Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい - Google 「Technical Writing」の紹介ブログ
Discussion