にたまご。

よく寝てよく食べる

Google Technical Writing One

GoogleのテクニカルドキュメントのWriting courseを受講しているので内容のサマリーを自分のメモ用に書き留めておく(適宜updateする)。 オープンソースや標準化系ドキュメントを書く人向けに見えるが、技術に関わる文章を書く機会のある人は見てみる価値ありかなと。

  • Terms:専門用語。一度省略型の専門用語を使うことにしたら、最初に省略形の断りを入れた上でそれを使い続ける。 Captive Portal Working Group(capport WG) is formed in 2015..... . The co-chair of capport WG is...

  • Acronyms:頭文字を使った省略単語;文書中で2,3回程度しか使わない単語はわざわざ頭文字省略しない。何回も出てくる場合は使うべし。また、明らかに省略前の単語が非常に長い場合は使うべし。

明確な文章を書くためには

  • あいまいな指示語表現は使わない:名詞に置きかえる、またはThis +名詞で使う。

  • 能動態と受動態:能動態の方が明確な表現になるため、基本的には能動態を使う。ただし、科学研究のレポートや論文等ではIt has been suggested~, XX were evaluated...のように受動態を使い控えめな表現にすることがある。

  • 強い動詞を使う: 文章の内容を明確にするために曖昧な動詞は使わないようにする(例えばoccurやhappenは弱い動詞、traggersやgenerateは強い動詞。他にもbe動詞は弱い動詞に分類される)

  • There is/areの使用頻度は減らす:主題+動詞を明確にした文で書く。

  • (optional)特定の形容詞と副詞はなるべく少なく:明確な文がゆるく定義されてしまうため。特に、テクニカルドキュメントにおいては、筆者による主観が強いように読み手にとられる(マーケティングっぽい印象になってしまう等)可能性があるため。(例:XX run amazingly fast ...)

コードと同じように文書も簡潔に書こう

短いドキュメントの読みやすさ・保守>長いドキュメントの読みやすさ・保守

  • 1センテンスに1アイデア(トピック、コンセプト、意見):長い文章をやめる。主張したい内容ごとに一文に切って整理する。ついつい接続詞を使って内容を詰め込みがちなので気をつけたい。

  • 長い文章はリスト化する形で書いてしまっても良い(特に操作する手順とか)

  • 無関係の単語は減らすor削除:我々は不必要な動詞を入れてしまうことがある。provide XX...と書いたけどXXを動詞にすればそれで十分だったパターンよくある。

  • 従属節は減らす:which/that/since/unless/untilなどで主節をサポートする場合がある。その場合は、従属節が主節のアイデアをあくまで補足・拡張しているという点で必要か、または別のアイデアについて語っているため別のセンテンスに分けるべきか精査してほしい。1センテンスに1アイデアを守ろう。

  • ThatとWhichはきちんと使い分ける:我々はどっちを使っても良いと思いがちであるが、一般的に米国では「which は不必要な従属節に使う(which節がなくても文章構造として成立する)」、「thatは文章構造的に必要な従属節に使う」とされている。

リストと表

良いリストや表は複雑な技術情報を整理してオーディエンスに見せてくれる。さらに技術系の読者は基本的にリストが好き。

  • リストの種類を把握しよう:順序関係ないものには通常の箇条書きを使う。物事の順序について書く際は数字の箇条書きを使う。一文にカンマで区切って物事を並べる埋め込み箇条書きというのもあるが、あまり効果的ではないので、最初に一文書き(だいたい.... as following:とか)+次の行から箇条書きが始まる形に変えよう。

  • リストアイテムは平行に:効果的なリストを作るには、同じ形式・濃度の情報を並べる。二つは能動態で書いたのにもう一つは受動態で書くなんてことは止めよう。

  • 数字の箇条書きのそれぞれの項目を命令動詞(start, launch, run etc.)で始める

段落

  • 段落の冒頭の文は重要である(読者が冒頭しか読まないかもということを含めて)。

  • 各段落に1トピックに集中する。次の段落やいくつか後の段落で起こることを書いてはならない。

  • 段落は長すぎず、短すぎず。長いと脅迫的に見えるし短すぎると1段落に対して3-5文がちょうどよい。

また、1つの段落は下記のような流れで構成すると良い。

  • WHAT: 何を読み手に伝えようとしているのか?
  • WHY: なぜ重要なのか?
  • HOW: どうやってユーザーはそれを使えば良いのか?

聴衆

  • 読み手を定義する:ソフトウェアエンジニア?学生(大学生or院生)?サイエンティスト ?非エンジニアポジション?Tech PM?彼らはすでに基礎知識として何を知っているか、逆に何を知らないか。
  • 読み手が何を学びたいか明らかにする
  • ナスカの地上絵や相撲、クリケット等の複雑な事柄を入れないこと。熟語の扱いも気をつけたい(非ネイティブだと意味がわからない等)

文書

  • Scope: 良い文書は最初にスコープが決められている。This document describes~◯◯
  • Non-scope: さらに良い文書は、スコープでないものについても述べられてる。This document does not describe~
  • オーディエンスを定める: I wrote this document for ◯◯ who support ◯◯ software. 他にも前提として読んでおくべきドキュメントがある場合は明記しておくことも良いだろう
  • エグゼクティブサマリーを冒頭に1ページつけておく
  • アウトラインを整理する
  • ドキュメントのモジュール化: トピックをセクションに分割する

句読点

  • コンマを使うか、ピリオドにするか。
  • 文章の曖昧さをなるべくなくすため、オックスフォードコンマを使うことが望ましい。
  • 異なる内容が一文に並ぶ場合はピリオドで。
  • セミコロン:ピリオドは異なる主張を分けるのに対し、セミコロンは関連性がある考えを一文に統合するためにある。
  • Em-dash:◯◯◯-◯◯と呼ばれているが-は〜
  • 括弧:重要でない文は括弧で。

(マークダウンについては割愛します)