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

Soft Skill

2023.05.192020.05.30

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

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

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

Technical Writing

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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