Googleのテクニカルライティング資料をまとめてみました

はじめに

私は仕事柄、仕様書など技術的な文書を書く、いわゆるテクニカルライティングの機会が多いです。今まで感覚で書いてきてしまったので、一度勉強しようと思っていました。
そこで今回は、Googleが公開しているテクニカルライティングの資料を読み、自分なりにまとめてみました。テクニカルライティングについて何も学んだことがない方は、参考にしてみてください。
私の解釈が入っていること、英語特有の言い回しについてはかなりの部分を省略していることをご了承ください。原文は英語ですが、おおむね平易な単語で書かれていますので、気になった方は原文に当たってみてください。このnoteへの修正依頼も大歓迎です。

用語

新たな用語や専門用語を定義する

・すでに良い表現がある場合は、その表現を使用する。
・自分で新たな用語を作った場合は、定義を明記する。たくさんの専門用語がある場合はどこかにまとめておく。

用語は一貫性を持って使う
ドキュメントの途中で用語の名前を変更してはいけない。ドキュメント中では用語に一貫性を持たせること。以下の例文では、Protocol Buffersという単語がいつの間にかprotobufsになってしまっている。

悪い例：
Protocol Buffers provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

長い用語については略語を使ってもよい。略語を使う際は、その旨を明記すること。

よい例：
Protocol Buffers (or protobufs for short) provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

頭文字を適切に使用する
頭文字を使った略語を使用する場合、初めに使用するときに、書き下した用語とセットで書いておく。以下の例文では、Telekinetic Tactile Networkが初めて出てくる際に、TTNと略すことを明記してある。

よい例：
This document is for engineers who are new to the Telekinetic Tactile Network (TTN) or need to understand how to order TTN replacement parts through finger motions.

略語と書き下した用語とを混在させないよう注意すること。

略語を用いると、文章は短くなるというメリットがある。一方で、読者は頭の中で略語を元に戻さなければならないというデメリットもある。

略語を使うか否かのガイドライン
・数回しか使用しない場合は、略語を定義しない。
・以下２点の指標を両方とも満たす場合は、略語を定義する。
　　・書き下すより略した方が圧倒的に短くなる。
　　・ドキュメント中に何度もその略語が出てくる。

代名詞の指すものをはっきりさせる
「それ」、「これ」などの代名詞を使う際は、その代名詞が何を指しているのかあいまいになる危険性がある。

代名詞を使う際のガイドライン
・名詞より後に代名詞を配置する。
・名詞と代名詞はできるだけ近くに配置する。
・ある名詞と代名詞の間に別の名詞が入る場合は、代名詞は使わずにもう一度元の名詞を使う。

能動態 vs. 受動態

受動態ではなく能動態を使う

能動態を使うメリット
・読者は頭の中で受動態を能動態に変換して理解することが多い。よって、能動態で書いておいた方が読者の負担が少ない。
・受動態は動作を間接的に表現するので、伝えたいことがあいまいになる。
・受動態は主語を省略することがある。よって、読者が主語を推測しなければならない。
・能動態の方が受動態より文章が短いことが多い。

明確な文

「強い」動詞を使う
文の中で動詞は最も重要。正確で具体的な「強い」動詞を選ぶこと。

弱い動詞の例：
・be動詞：is, are, am, was, wereなど
・occur (起こる)
・happen (起こる)

強い動詞や言い回しを使うと文章がより明確になる。
※英語と日本語で差がありますが、因果関係や主語が明確になる表現を選ぶとよいと思います。

修正前：投稿ボタンを押したとき、エラーが起きます。
修正後：投稿ボタンを押すことが、エラーを引き起こします。
※弱い文章では、ボタンを押すことが引き金であることが明確でない。

短い文

テクニカルライティングの法則
・短いドキュメントの方が早く読める。
・短いドキュメントの方がメンテナンスが楽。
・文を追加するほど間違いも増える。

１文１メッセージ
長い文は短い文へ分解する。１つの文には１つの意味しか持たせないようにする。

長い文：
1950年代後半は、1957年にIBMがFortranを開発し、翌年にジョン・マッカーシーがLispを開発したことで、プログラマが反復や再帰といった手法で問題を解くことができるようになり、プログラミング言語にとって鍵になる時代だった。

短い文：
1950年代後半は、プログラミング言語にとって鍵になる時代だった。1957年にIBMはFortranを開発。翌年にはジョン・マッカーシーがLispを開発した。これにより、プログラマが反復や再帰といった手法で問題を解くことができるようになった。

長い文は箇条書きにする
長い文の中に、「または」などを使って多くの内容が羅列されている場合には、箇条書きにしてみるとよい。

長い文：
ループ中に処理を省く場合には、break文（現在のループから抜ける）またはcontinue文（現在のループの残りの処理をスキップする）を使います。

箇条書き：
ループ中に処理を省く場合には、以下のいずれかを使います。
・break文：現在のループから抜ける
・continue文：現在のループの残りの処理をスキップする

いらない単語は削る
必要ない単語は削る。冗長な表現はより短い表現に置き換える。
※日本語の場合は「～することができる」を「～できる」にするなど。

箇条書きと表

適切な箇条書きを選ぶ

箇条書きの種類
・バレット型（bulleted lists）
・番号型（numbered lists）
・組込型（embedded lists）
※適切な訳がわかりませんでした

バレット型
「・」を使った箇条書き。順序が関係ない場合に使う。

Bashにはstringを扱う以下の機能がある
・stringの初めから途中までを削除する
・ファイル全体を１つのstring変数へ読み込む

番号型
数字を使った箇条書き。順序が重要な場合に使う。

サーバーの再設定方法
１．サーバーを停止する
２．設定ファイルを編集する
３．サーバーを再起動する

組込型
文章中に羅列した形式。技術文書を残す上では悪い手法なので、他の箇条書きに変換すべき。

箇条書きの項目は並列に
よい箇条書きは、各項目が並列になっている。

並列に保つべきもの
・文法（文章の構成）
・論理的なカテゴリ
・大文字、小文字（英語の場合）
・句読点

以下の箇条書きは、並列を保てている。

夜のルーティーン
１．夕食を食べる。
２．お風呂に入る。
３．歯を磨く。

以下の箇条書きは、並列を保てていない。

夜のルーティーン
１．夕食を食べる。
２．お風呂に入る
３．歯磨き

よい表を作る
表は目立つ。文字情報よりもまず表に目が行く。

表を作る際のガイドライン：
・各列にわかりやすいヘッダーをつける
・セル内の文量は抑える
・同じ列のデータは同じカテゴリにする

箇条書きや表にタイトルをつける
箇条書きや表が説明している内容がわかるようなタイトルをつける。タイトルの末尾は「：」で締める。

段落

ライティングの極意：
・トピックどうしの関係性を明らかにする
・読者が理解しやすいよう論理的に並べる

適切なリード文を
段落のリード文（段落の最初の文）は最も重要。その段落の要旨を表すリード文を書くこと。

適切なリード文：
ループ処理とは、同じコードブロックを繰り返し実行することである。例として、ある行がピリオドで終わっているか否かを調べるコードを書く場合を考えてみよう。100万行処理するためには、100万回実行されるループ処理を作ることになる。

不適切なリード文：
コードブロックとは、同一関数内の一連のまとまりのことである。例として、ある行がピリオドで終わっているか否かを調べるコードを書く場合を考えてみよう。100万行処理するためには、100万回実行されるループ処理を作ることになる。

１段落１トピック
前の段落や次の段落の内容は書かない。現在の段落で扱う内容のみに絞る。

段落は長すぎても短すぎてもダメ
長すぎる段落は誰も読まない。３～５文程度が適切。１文しかない段落は他の段落に吸収させる。

what, why, howに答える

良い段落は以下の３つの質問への回答になっている：
１．読者に何を伝えたいか？
２．読者にとってなぜ重要なのか？
３．読者はどうすればこの知識を活用できるか？また、読者はどうすれば著者の主張の信頼性を確かめられるか？

what, why, howに答えている良い例：
<whatはじめ>garp()関数は、データセットの平均値と中央値の差を返します。<whatおわり><whyはじめ>多くの人は、平均値が真実を反映していると信じて疑いません。しかし、平均値は一部のとても大きなまたは小さなデータに大きく影響を受けてしまうのです。<whyおわり><Howはじめ>平均値が一部のとても大きなまたは小さなデータに多きく影響を受けているか確かめるために、garp()関数を呼び出してください。garp()の値が比較的大きいときよりも小さいときの方が、より平均値に意味があるということになります。<Howおわり>

読者

ドキュメントには、読者が必要としているがまだ得られていない情報を書くべき。

よいドキュメント = 読者が必要としている知識とスキル - 読者が持っている知識とスキル

やるべきこと：
・対象読者を決める
・読者が学ぶべき知識を決める
・ドキュメントを読者に合わせる

対象読者を決める
まず、対象読者の役割を決める。
役割だけでなく、その分野にどれくらい精通しているかにも注意すべき。プログラミング言語や担当プロジェクトによっても、読者の詳しさにはバラつきがある。

対象読者の分析例

プロジェクトZylmonの対象読者：
・ソフトウェアエンジニア
・テクニカルプロダクトマネージャ
対象読者の前提知識：
・Zylmon APIに似通ったZylieune APIをすでに知っている。
・C++は知っているが、新しいWinged Victory開発環境でのビルド方法は知らない。
・大学で線形代数を学んでいるが、行列演算の復習が必要である。

読者が学ぶべき知識を決める
読者が学ぶべきことを全て書き出す。

ドキュメントを読み終えた読者は以下の要件を満たしていること：
・Zylmon APIを使ってホテルを価格ごとにリストアップできる
・Zylmon APIを使ってホテルを場所ごとにリストアップできる
・Zylmon APIを使ってホテルをユーザー評価ごとにリストアップできる

ドキュメントを読者に合わせる
読者に合ったドキュメント作成のための要素をいくつか挙げる。

語彙
使う語彙を読者に合わせる。
チーム内の略語やプロジェクト固有の実装などに注意する。

知識の呪い
詳しい人の説明が、初学者にとってはわかりにくいことがある（知識の呪い）。「知っていて当然」と説明を飛ばしてしまわないように注意する。

シンプルな言葉を
英語のドキュメントを作成するときは特にシンプルな言葉を心掛ける。英語がネイティブではない人が多いため。

文化的中立性と熟語
特定の文化に精通していないと理解できない表現をしない。例え話を使用する場合などは注意する。
また、熟語も地域性があるため注意する。特に昨今は機械翻訳を使用する読者も多いため、熟語が混ざっていると意味を理解できないことがある。

ドキュメント

全ての段落を一連のドキュメントとして仕上げる必要がある。

ドキュメントが扱う範囲を明示する
冒頭でドキュメントが扱う範囲を明示する。

例：
このドキュメントではプロジェクトFrambusの全デザインについて述べる。

扱わないことについても述べておくとよい。

例：
このドキュメントでは関連プロジェクトFroobusのデザインについては述べない。

範囲を明確にしておくメリット：
・読者が読みやすい
・著者が書いている途中に混乱せずにすむ

想定する読者を明示する

例：
これはプロジェクトFrambusのテストエンジニア向けのドキュメントです。

読者の役割だけでなく、前提知識や経験についても述べるとよい。

例：
このドキュメントは、行列演算を理解している読者を想定しています。

他のドキュメントを参照するように促す場合もある。

例：
まず「プロジェクトFrambusに加わる方へ」を読んでおいてください。

読者のために書く
ドキュメントを仕上げるために、読者の定義について注意すべきことを述べる。

読者を定義する

ドキュメントの内容を決めるための質問：
・対象読者は誰か？
・ドキュメントを読む前に読者が持っている知識は何か？
・ドキュメントを読んだ後、読者が知っている/できるようになっていることは何か？

例えば、新しいソーティングアルゴリズムを作った場合を考えると、以下のようになる。

・対象読者は弊社のソフトウェアエンジニア全員とする。
・読者は、学生時代にソーティングアルゴリズムを学んでいることとする。しかし、そのうち約25%は何年もソーティングアルゴリズムを実装/評価していないものとする。
・このドキュメントを読むと：
１．このアルゴリズムがどう動いているかわかる。
２．好きな言語でこのアルゴリズムを実装できる。
３．どういう場合なら、このアルゴリズムが有名なクイックソートよりも優れているかを理解できる。
４．特定の極端な場合ではパフォーマンスが低下することを理解できる。

構成を考える
読者を定義したら、読者がドキュメントを読んで理解できるように構成を考える。アウトラインの例を示す。

1. アルゴリズムの概要
     a. Big O
     b. 簡易コードでの実装
2. C言語での実装例
     a. 他の言語での実装ポイント
3. アルゴリズムの詳細
     a. 最適なデータセット
     b. 極端な場合で起こる問題

定義した読者像を使って、内容を吟味していく。
例えば、アルゴリズムの詳細を読者は忘れているという想定であれば、アルゴリズムのチュートリアルへのリンクを貼っておくなどの工夫をするとよい。

トピックを塊に分解する
プログラミングと同じく、ドキュメントも塊ごとに分けた方がよい。
塊にも大中小の粒度がある。まず概要を理解して、詳細を理解していけるようにすること。
構成に迷った場合は、数分自由に書くなり喋るなりして、以下の項目をチェックするとよい。

構成を考えるときの手引き：
・詳細ではなく、ざっくりと概要を説明したか？
・読者が結論にたどり着けるように段階を踏んでいるか？
・説明する順番を伝えているか？

まとめ

・用語に一貫性を持たせる
・曖昧な指示語は避ける
・受動態より能動態を使う
・曖昧な動詞より正確で具体的な動詞を使う
・１文に１メッセージとする
・長文は箇条書きに変換する
・不要な語は削除する
・箇条書きは、順番が重要ならバレット型、そうでなければ番号型を使う
・箇条書きの項目は並列を保つ
・番号型の箇条書きは命令形にする
・適切に箇条書きと表を使う
・段落の概要となる素敵なリード文を書く
・１段落１メッセージとする
・読者が学ぶべき内容を定義する
・ドキュメントを読者に合わせる
・ドキュメントの冒頭に要点を示す