どういう記事
Google Technical Writing Technical Writing Oneを通して、自分が学んだことをまとめる記事です。
Google Technical Writingとは
Googleが出している技術文書の書き方を示した教材です
英語だが平易なものが多いのでなんとか読めるし、日本語の文章に置き換えても活用できるものが多いのですが、
今回は内容量の観点から「Technical Writing One」のPre-classの内容のみ記載します。
学んだことの概要
- 単語の使い方
a. 馴染みのない単語は定義する
b. 用語は一貫して使う
c. 頭字語(FBIやWHOなど)を適切に使用する
d. 曖昧な代名詞を認識する - 能動態と受動態
技術文書には能動態を使い、誰が誰にを明確にする - 文章は明確に
a. 強い（強調できる）動詞を選ぶ
b. 特定の形容詞と副詞を最小限に抑える - 短い文章に
a. 各文を一つの意見に集中させる
長い文章は分割する
b. 長い文章をリストに変換する
箇条書きや番号付きリストに書き換えられないか検討する
c. 無関係な単語を削除または減らす - リストとテーブル
a. 正しいリストを選択する
b. リスト項目を並列に保つ
c. 番号付きリストの項目は命令形で始める
d. 項目には適切な句読点をつける
リスト項目が文の場合は適切に句読点をつける
e. 役に立つテーブルを作成する
f. リストと表に導入をつける - 段落
a. 冒頭文を重要視する
冒頭文は段落の注目すべきポイントを確立するので集中して記載すべき
b.各段落を１つのトピックに集中させる
段落は独立した論理単位であるべき
c. 段落は程よい長さにする
d. 何・何故・どのように に答える - 読者
a. 対象の読者を定義する
b. 読者が学ぶことを定義する
c. 読者に合わせて文書を調整する - 文書
a. 文書の範囲を明記する
b. 読者を明記する
c. 冒頭で大事な点を要約する
d. 読者に向けて書く
学んだことの詳細
1-b. 用語は一貫して使う
下記の文章が印象的でした。私も、推理小説を読むときなどにはこれを意識しているにも関わらず、技術文書ではあまり気にしていませんでした。
When I encounter two words that seem to be synonyms, I wonder if the author is trying to signal a subtle distinction that I need to track down and understand.
同義語のように見える 2 つの単語に遭遇したとき、著者は私が追跡して理解する必要がある微妙な違いを伝えようとしているのではないかと疑問に思います。
1-c.頭字語を適切に使用する
WHOやFBIなど複数の単語から構成された合成語の頭文字をつないで作られた語のことを頭字語と言います。
そもそも頭字語って言うんですね。（無知。。。）
略語として括っていました（略語の一種ではあるので間違ってはいない）
用語全体をフルスペルで書き、その上で頭字語を（）で括ることを推奨しています。
例：Telekinetic Tactile Network (TTN)
また、下記の文章が印象的でした。確かに見慣れない頭字語がたくさん出てくる文章は理解に時間がかかりますね。
Well, acronyms do reduce sentence size. （一部省略） However, acronyms are really just a layer of abstraction; readers must mentally expand recently learned acronyms to the full term. For example, readers convert TTN to Telekinetic Tactile Network in their heads, so the "shorter" acronym actually takes a little longer to process than the full term.
確かに、頭字語を使用すると文のサイズが小さくなります。（一部省略） 読者は最近学んだ頭字語を頭の中で完全な用語まで拡張する必要があります。 たとえば、読者は頭の中で TTN を Telekinetic Tactile Network に変換するため、「短い」頭字語は実際には完全な用語よりも処理に少し時間がかかります。
そのため、頭字語を使う場合は、下記が推奨されています。
- 頭字語は、完全な用語よりも大幅に短くなるようにする
- その頭字語は、文書内で何度も登場する
1-d.曖昧な代名詞を認識する
代名詞を使う場合は、下記が推奨されています。
- 代名詞は名詞を導入した後にのみ使用する
- 代名詞を指示名詞のできるだけ近くに配置する
※名詞と代名詞が5単語以上離れている場合は、代名詞を使用する代わりに名詞を繰り返すことを検討すること - 名詞と代名詞の間に2番目の名詞を導入する場合は、代名詞を使用する代わりに名詞を再利用する
「それ」「それら」「これ」「あれ」は混乱を引き起こす原因になりかねないので明示的な単語に置換したり、明示的にするための単語を追加したりすることが推奨されています。
3-a.強い（強調できる）動詞を選ぶ
動詞が技術文書の大半を決めるとも言えるため、より適切な動詞がないか検討することが推奨されています。
自分は、手順書を書くときに「〜を行う」と書きがちなのですが、より良い単語がないか検討すべきと感じました。
3-b. 特定の形容詞と副詞を最小限に抑える
形容詞や副詞は定義が大雑把で主観的になる傾向があるため、客観的な数値情報にすることが推奨されています。この辺りは、Writingでは意識できているものの、Speakingではいまだに使ってしまいがちなので気をつけたいです。
4-c. 無関係な単語を削除または減らす
読み手に新しい情報を与えずに文章量を増やしてしまうような単語を削除することが推奨されています。
私がよく使ってしまいがちなのが、「〜の書き換えを行う」という表現です。「〜を書き換える」だけで必要十分な表現なのでこの辺りはまだ訓練が必要と感じました。
5-a.正しいリストを選択する
技術文書で使われるリストは下記が主流です。
- 箇条書きリスト
- 番号付きリスト
- 埋め込みリスト
順序のない項目には箇条書きリストを使用します。
つまり、並び替えてもリストの意味が変わらないものでないと箇条書きリストを使ってはいけません。
埋め込みリストは、文章内に埋め込まれたリストなので箇条書きリストや番号付きリストに変換することが推奨されています。
例(不思議な例ですね)
ラマキャッチャー API を使用すると、呼び出し元はラマの作成とクエリ、アルパカの分析、ビキューナの削除、ヒトコブラクダの追跡を行うことができます。
これは4-bでも出てきた通り、下記のようにすべきです。
llamacatcher API を使用すると、呼び出し元は次のことを行うことができます。
・ラマを作成してクエリします。
・アルパカを分析します。
・ビクーニャを削除します。
・ヒトコブラクダを追跡します。
5-b.リスト項目を並列に保つ
並行なリスト内の全ての項目は並列である必要があり、
それらは次のパラメータが一致するようにすべきとされています。
- 文法
- 論理カテゴリ
- 句読点
- 大文字化（大文字・小文字を揃える）
練習問題に、能動態と受動態が入り混じっているリストの例が出題されていました。
この辺りは意識していないと失念してしまいそうです。
5-e.役に立つテーブルを作成する
テーブルを作成するときのガイドラインは次の通りです。
- 各列に意味のあるヘッダーのラベルを付ける
- 各列に何が含まれているかを読者に推測させない
- 表のセルにテキストを入れすぎない
- 表のセルに 3 つ以上の文が含まれている場合は、その情報が他の形式に属しているかどうかを自問する
- 異なる列には異なるタイプのデータを保持できるが、個々の列内で並列処理が行われるように努める
- たとえば、特定のテーブル列内のセルに、数値データと固有名詞が混在しない
5-f.リストと表に導入をつける
各リストや表において、それらが何を表しているのかを紹介することを推奨しています。
確かに、表を細かく見ないと何を示したいのかわからない表は不便ですね。
例
次のリストは、主要なパフォーマンス パラメータを示しています。
次の表は、当社の製品の機能と主要な競合他社の機能をまとめたものです。
6-c. 段落は程よい長さにする
長い段落は視覚的に威圧的であるため、3文〜5文程度の段落を推奨しています。
逆に短すぎる場合はまとまった段落やリストにできないかを検討することが推奨されています。
6-d. 何・何故・どのように に答える
優れた段落とは次の３つの質問に答えることができるものだと、本文書中では主張しています。
- 読者に何を伝えようとしているか
- 読者が何故これを知るべきなのか
- 読者はどのようにこれらを使うのか、あるいはどのようにしてこれらが正しいと知ることができるか
7. 読者
この章では「優れた文書=読者がタスクを実行するのに必要な知識とスキルである」と定義しています。
7-a.対象の読者を定義する
本文書中では、下記のようにして対象の読者を定義するとしています。
まずは、読者の役割を特定する必要があります。
たとえば、学生なのか非技術職なのかなどです。
ただし、役割だけでなく読者がどれくらいその知識に「近い」かも考慮する必要があります。
たとえば、インフラエンジニアは、Webエンジニアの領域には詳しくない可能性が高いです。
時間も「近さ」に影響します。経験値やそれらを学んだであろうタイミングも考慮に入れるべきです。
7-b. 読者が学ぶことを定義する
本文書中では、目的を達するために読者が学ぶべきことを全てリストアップする必要があるとしています。
また、必要に応じて、読者が実行する必要のあるタスクについてもリストアップする必要があるとしています。
7-c. 読者に合わせて文書を調整する
下記のようなパラメータに注目し、読者の好奇心を満たす文書にすべきと推奨されています。
- 語彙と概念
- 対象読者がその略語を理解しているか
- 普通は、思っている以上に説明する必要がある
- 知識の「呪い」
- 自分が知っていることを初心者は知らないということを忘れがち
- 簡単な言葉
- 複雑な単語よりも単純な単語を優先させる
- 文化的中立性と慣用句
- 文化的中立性を意識し、慣用句を使わない
8-a. 文書の範囲を明記する
優れた文書は、その範囲や含まれるべきであるにも関わらず対象外とする範囲を定義するとしています。
例
この文書では、Project Frambus の設計について説明します。
この文書では、関連テクノロジである Project Froobus の設計については説明しません。
また、これは書き手にとっても執筆時やレビュー時に役立ちます。
8-b. 読者を明記する
優れた文書は、対象読者を明記するとしています。また、前提条件となる知識や経験の指定も、明記することでさらに役立ちます。
8-c. 冒頭で大事な点を要約する
文書の冒頭で読者の本質的な質問に答えましょう
Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, the start of any long document is the hardest page to write. Be prepared to revise page one many times.
プロのライターは、読者が 2 ページ目に到達する可能性を高めるために、1 ページ目にかなりのエネルギーを集中します。 ただし、長い文書の始まりは、書くのが最も難しいページです。 1 ページ目を何度も改訂する準備をしてください。
また、読者がすでに理解しているであろう概念との、比較や対照を使うことも推奨されています。
例
This new app is similar to the Frambus app, except with much better graphics.
この新しいアプリは、グラフィックスがはるかに優れている点を除いて、Frambus アプリに似ています。
8-d. 読者に向けて書く
下記が推奨されています。
-
読者のニーズを定義する
- 対象ユーザは誰か
- 対象ユーザの目的は何か、なぜこの文書を読んでいるのか
- この文書を読む前に、読者が知っていること（前提知識）は何か
- この文書を読んだ後に、読者が知っておくべきこと、できるようになることは何か
-
読者のニーズに合わせて文書を整理する
- 読者が必要な情報を入手できるように文書を整理する、整理する際は、前のセクションへの回答に基づく
最後に
以上が、自分がGoogle Technical Writing Technical Writing Oneを通して学んだことです。
これまでにも文章の書き方に対する研修等は受講していましたが、改めて技術文書に特化した内容を学ぶことができました。
今回は、都合上、例や練習問題を省略してしまいましたが、実際の記事の方が何倍も腹落ちします。ぜひ学んでみてはいかがでしょうか。