Google の Technical Writing に学ぶ良質な文書の書き方

  • 2020.05.30
  • IT
Google の Technical Writing に学ぶ良質な文書の書き方

良質な文章を書くのは簡単なことではありません。アウトプットの質を向上させるためには、そのための技術を学習しなければいけません。特に技術文章の場合、専門分野の知識を明確に説明できることが重要です。

今回はGoogle が公開している技術文章をわかりやすく書くためのドキュメントを紹介します。英語のドキュメントですが、難易度は高くないため翻訳サービスなどを使えば問題なく読めます。

ドキュメントのサマリーを紹介し、自分なりに大事だと思ったところをカテゴリ分けして補足していきます。

Technical Writing

今回紹介するサイトはこちらです。Google が公開している技術者向けのドキュメント作成指南書です。

https://developers.google.com/tech-writing

大まかに次の2つで構成されています。それぞれはいくつかのドキュメントで構成されて扱っている各要素の説明をしています。

  • Technical Writing One
  • Technical Writing Two

サマリー日本語訳

各構成は最後にサマリーで締められています。それぞれざっくりと日本語訳にしました。これを読むだけでもそれなりにエッセンスを汲み取れます。

Technical Writing One

  • 一貫した用語を使う
  • 曖昧な代名詞は避ける
  • 受動態より能動態を優先する
  • 強い動詞を選ぶ
  • 曖昧な動詞より特定の動詞を選ぶ
  • 文毎に1つの考えに集中する
  • 長い文章はリストにする
  • 不要な言葉は削除する
  • 順番が重要なときは番号付きリスト、そうでないときは箇条書きを使う
  • リストの項目は並列にする
  • 番号付きリストの項目は命令形にする
  • リストと表は適切に説明する
  • 文章の中心となるポイントを序文に書く
  • 段落毎に1つの話題に集中する
  • 読者が何を学びたいかを定義する
  • 文書を読者に合わせる
  • 文書のキーポイントを文書のはじめにおく

Technical Writing Two

  • スタイルガイドに合わせる
  • 読者の好みを考える
  • 文書を読み上げてみる
  • 下書きを書き終わった後、時間を置いて見返す
  • 良い編集者を見つける
  • 文書のアウトラインを作る
  • 文書のスコープと前提要件を紹介する
  • タスクベースの見出しを優先する
  • 情報を段階的に開示する
  • 図表を作成する時には説明文を考える
  • 図に情報量を増やしすぎない
  • 画像に視覚的な注目点を作る
  • 理解しやすい簡潔なサンプルコードを書く
  • コードのコメントは短く、ただし明確で簡潔にする
  • コード内の直感的でない物を説明するために集中する
  • 例だけでなく反例も提示する
  • 複雑さの範囲を示すサンプルコードを提示する
  • 継続的に見直す
  • 異なるカテゴリのユーザーに異なる文書を提供する
  • 読者が既に知っているものに例える
  • 例を使用して概念の理解を強化する

個人的ポイント補足

文書を書くとき全般

文書を書くときに意識するべき全体的なポイントです。

  • スタイルガイドに合わせる
  • 読者が何を学びたいかを定義する
  • 下書きを書き終わった後、時間を置いて見返す
  • 良い編集者を見つける

特にこの Technical Writing では「audience」という言葉が頻繁に使われていました。読者を意識した文書を書くのが大事ということでしょう。

良質なドキュメントは、「読者が必要としている知識や能力」と「読者の現在の知識や能力」の間を補填する物です。これに加えて、論理的にそれを届ける文章の組み立てが大事です。

  1. 読者に何を伝えようとしているか
  2. 読者がこれを知ることはなぜ重要か
  3. 読者はこの知識をどのように利用するべきか、もしくはどのように情報を正しいと確かめるべきか

文章の組み立て方

文章を組み立てるときに意識するべきポイントです。

  • 文書のアウトラインを作る
  • 文章の中心となるポイントを序文に書く
  • 文書のスコープと前提要件を紹介する
  • 段落毎に1つの話題に集中する
  • 文毎に1つの考えに集中する

言葉の使い方

文書を書くときに使う言葉の選び方や使い方のポイントです。

  • 一貫した用語を使う
  • 曖昧な代名詞は避ける
  • 受動態より能動態を優先する
  • 不要な言葉は削除する

受動態は主語が不明確になりがちなので使うのを避けます。能動態を使うことで誰が何をするのか、文章で伝えるべきポイントがぶれなくなります。日本語だと丁寧語や尊敬語なども受け取り方が違うものになる原因になります。

用語の使い方も重要です。長い専門用語を略すときは最初にフルスペルを記載してカッコで略語を記載します。頻繁に出てくる用語は略語を使うとシンプルになります。

リストの使い方

リストを使うときに意識すべきポイントです。

  • 長い文章はリストにする
  • 順番が重要なときは番号付きリスト、そうでないときは箇条書きを使う
  • リストの項目は並列にする
  • 番号付きリストの項目は命令形にする

文書で使えるリストは2種類あります。

  • 箇条書き
  • 番号付きリスト

項目の順番を入れ替えても問題ないときは箇条書き、順番が大事なときは番号付きリストを使うというのが選択のポイントです。さらに、各項目はそれぞれ論理的に同じグループに分けられるよう粒度を揃えます。

図表の使い方

図表を使うときに意識すべきポイントです。

  • 図表を作成する時には説明文を考える
  • 図に情報量を増やしすぎない
  • 画像に視覚的な注目点を作る

きちんと図表の説明文を入れることで、伝えたいことが明確になります。さらに丸や四角で図中の注目すべき部分を示すことで、見て欲しいポイントがはっきりとします。

まとめ

こうして文書の書き方を改めて勉強してみると、普段意識できていないことが多くて発見が多いです。読みやすさと文書の内容が一致するとは限りませんが、どちらもそろってこそ良質な文書になります。日々意識してアウトプットの質を向上できるようにしていきたいです。