はじめに
最近聴いたe34.fmの7: News September 2021 - e34.fm の中で、GoogleがTechnical Writing | Google Developersを公開していることが紹介されていました。
ちょうど設計書や技術方針などの技術文書を書いたり、レビューをする機会が多かったので、試しに読んでみました。
今回は、その内容について忘備録としてメモを残しておきます。
Technical Writing Courses for Engineerの構成
こちらのページにあるようにTechnical Writing Courses for Engineerは、以下の２つで構成されています。
- Technical Writing One
- Technical Writing Two
Technical Writing Oneはテクニカルライティングの基礎を学ぶ内容となっていて、Technical Writing Twoはテクニカルライティングの４つのトピックについて実践する内容になっています。 それぞれPre-classとIn-classがあり、Pre-classが知識を学ぶ時間, In-classが学んだ知識を補強する時間になっています。 今回は、Technical Writing OneのPre-classの内容を書いていきます。 内容については多少意訳している箇所もあるので、詳しく気になる人は、公開されている一次資料 を読んでください。
メモ
Words
- すでにある用語なら、定義し直すのではなく、引用すること
- 定義しなくてはいけない用語がたくさんあるなら用語集を作ること
- ソースコードのコンパイルと同じように、途中で名前が変わってしまったら理解できないドキュメントになるので、名前に一貫性を持たせること
- 正式名称が長く、ドキュメントの中に頻繁に登場する用語には略名を使うこと
- 略名を使う場合は、正式な名前のあとに()をつけて略名を記載すること
- 正式名称を書くか略名を書くか？
- 略名の場合読み手は正式名称を意識して読む必要があるため、脳内の処理は正式名称よりも略名を読む方が高い
- 曖昧な代名詞は、プログラミングのポインタと同じで脳内でNPEが起こる
- 大半のケースでは代名詞はやめて名詞を繰り返し使う方がよい
- 代名詞を使う場合は、その直後に名詞を補足すること
Active Voice
- 誰が誰に何をしているのかを特定すること
- 読み手は脳内で受動態を能動態に変換するので、受動態で書かれていると読み手に負担がかかる
- 受動態は能動態に比べて文が長くなる傾向がある
- 受動態はアクターが省略されるときがあるため、読み手が混乱してしまう
Clear sentences
- Technical Writingでは明快さが一番重要である
- 読み手を引きつけて教育するために、適切な強い動詞を選ぶこと
- 不正確で弱い一般的な動詞を避けること
- 英文だとbe動詞, happen, occur
- A occur when B → B trigger A
- A happens when B → Actor generates A when B
- be 形容詞 to 動詞 → 副詞 動詞
- 英文だとbe動詞, happen, occur
- 不正確な動詞を使っている箇所は、アクターが省略されていたり、受動態の形になっている兆候を示すことがある
- 形容詞と副詞は技術ドキュメントにおいては、主観的である傾向が強いため避ける
- 例「フラグAを有効にすると、アプリケーションが非常に高速になる」
- 非常に高速とは？主観では？という気持ちが生まれてしまう
- この場合は、事実としてあるデータで置き換えること
- 「フラグAを有効にすると、アプリケーションの実行が225〜250％速くなる」
- 例「フラグAを有効にすると、アプリケーションが非常に高速になる」
Short sentences
- エンジニアは以下の理由からコードを短く書こうとする
- 短いコードは一般的に読みやすい
- 短いコードはメンテナンスがしやすい
- 短いコードは障害点を減らす
- Technical Writingでも同じ
- 短い文は長い文より読みやすい
- 一つの文には一つの考えのみを記述すること
- 長い文はリストに変換すること
- 冗長な単語や言い回し削除すること
- causes the triggering of logging → triggers logging
- この時点で → 今
- 〜することができる → 〜できる
- 従属節によって、一つの文に複数の考えが記載されないようにすること
- アメリカでは、thatは重要な従属節を表し、whichは重要では無い従属節を表す
Lists and tables
- 埋め込みリストは避けること
- 埋め込みリストの例「このAPIは、xxxの登録、xxxの更新, xxxの削除, を行います」
- リストにするときは、内容や形式を揃えること
- 表のセルに文を含めすぎないようにすること
- 表やリストを紹介する文を記述すること
Paragraphs
- 冒頭文が段落の中で最も重要
- 各段落を一つのトピックに集中させる
- 段落を書く場合は、3~5文程度にすること
- 7文を超える場合は分割を検討すること
- 段落の中の構成は以下を含めること
- 読み手に何を伝えたいのか
- なぜそれを伝えることが重要なのか
- その情報を読み手はどのように使うのか
Audience
- 優れたドキュメント = 読み手がタスクを実行するために必要な知識とスキル - 読み手の今の知識とスキル
- 対象の読み手を定義すること
- 読み手がタスクを実行するために必要なことを一覧化すること
Documents
- ドキュメントのスコープを定義すること
- ドキュメントの対象者を明示すること
- ドキュメントの前提条件となる知識や経験を明示してもよい
- 重要なポイントを要約して明示すること
Punctuation
- 二つの考えを区切るために句点を使うことを避けること
- テキストが重要では無いことを読み手に伝えるためには括弧を使うこと
- ただしTechnical Writingでは、括弧を使うことは最小限に留めること
感想
読んでみた感想としては、普段英文でドキュメントを書かないエンジニアも一読する価値のある資料だと思いました。 代名詞の扱いや段落のキーセンテンスの話など、論文を書いたことがある人なら一度は指摘されるような内容についてもわかりやすく書かれていました。 コロンやセミコロンの扱いや、that節/which節の違いなど、実際に英語でドキュメントを書く際に見返したい内容が書かれているのもよかったです。
日本語でテクニカルライティングの資料というとLINE社が公開している LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた - LINE ENGINEERING があるので、こちらも読んでみようと思っています。
