不要不急の外出を避けて暮らしていたら体重がすごく増えていました。
とてもショックだったので、頑張って元の体重に戻そうと思います。

今回は弊社のとある社員が「Google のテクニカルライティング講座を読む」というテーマで話しました。

---

最近、文章を書く機会が少なくなったなーと思っていました。
Slack や Twitter なんかにちょっとした呟きをすることはあっても、長文はまず書きません。
いざそういう業務が舞い込んできても対応できそうにない。

そんなことを考えていたときにこちらの記事を見かけ、Google のテクニカルライティング講座の存在を知り興味を持ちました。
ソフトウェアエンジニア、情報科学専攻の学生、プロダクトマネージャー向けの講座で、S2にとってはお誂え向きかなと思い読んでみたら面白かったので、少し内容を紹介しようと思います。

※全編英語で書かれたもののため、日本語では説明しづらい・取り入れづらい箇所もあります。

用語

初めの章は用語についてです。

用語を使うときは、よく知られている用語を既存の説明にリンクし、初めて導入する用語の定義をしましょう。
また、略語を使うことでテキストの文字数を減らせますが、読み手の頭の中では元の言葉が何度も展開されてしまうため、あまり有効ではありません。

• 略語によって著しく文字数を減らせるとき
• 文章の中に何度も出てくるとき

この両方の条件を満たすときだけ略語を使うのが推奨されています。

受動態と能動態

ほとんどの文章は能動態で書きましょう。
読者は受動態を見ると、頭の中で能動態に書き換えてしまいがちです。さらに、受動態は間接的で、書き手の意図をぼやかしてしまうという側面があります。
そもそも能動態の方が大抵の場合、文章を短く書けるそうなので、そういった面でも能動態で書く方が良いらしいです。
主語を省略した、動詞から始まる文章を書くときにも、読者を主語に据えた表現をするように心がけましょう。

とはいえ、何もかも能動態にすればいいというわけでもなく、参考までに確認した日本語版のスタイルガイドによると、利用者が行った操作の結果や、利用者から見て自動的に行われる動作は受動態で表現するのが良いと書かれていました。

明解な文章

ホラー作家が人を怖がらせるような文章を求められているように、コメディ作家には面白い文章が求められます。同様に、テクニカルライターに求められるのは明解な文章です。
そして、明解さを表現するには強い動詞を使うのが有効的です。

強い動詞とは、、、説明によると、

• be 動詞や occur, happen などの受け身な感じのする動詞を弱い動詞
• ensure, trigger, generate などの能動的な感じのする動詞を強い動詞

とありました。
先ほどの章でもあったように、能動的な文章の方が理解しやすいという考え方が元になっているみたいです。

もう一点、there is / are という表現を減らすのも効果的だと言っています。
何かものがあるとき、それに注意を向けるために使われるのが there is / are なのですが、真の主語と動詞を見つけ出し文頭に置く訓練をすることで、意味が通りやすく明解な文章を作成できるようになります。

こちらは例文ですが、

There is a variable called met_trick that stores the current accuracy.

The met_trick variable stores the current accuracy.

二つの文章は There is を使っているかいないかだけで意味は同じです。テキストにするなら下のように短く書くようにしましょう。

文は短くする

短いコードは読みやすく、メンテナンスもしやすい、そしてバグを招きにくい。
文章にも同じことが言えます。文章は簡潔に。一つの文には一つだけ意図を持たせるようにし、複数の意図を含む、もしくは、文章が長くなってしまうときには文を分けたり、リストにするのが良いでしょう。

余計な表現を使わないことも大切です。

• at this point in time → now
• determine the location of → find
• is able to → can

英語の例ですが、意味が通るのであればこのように短い表現を使いましょう。

リストと表

先ほどリストの話がチラッと出ましたが、
リストには、

• 箇条書き
• 番号付き
• 埋め込み

の三つがあります。
箇条書きはリストの内容が順番を問わないとき、番号付きは順番を考慮する必要があるときに使います。
埋め込みリストというのは、文章中でカンマ区切りに並べるような書き方のことですが、テクニカルライティングの場合、情報を提示するのに不十分なのでやめた方が良いと言われています。

リストを使用する際は、

• 文法
• 論理的カテゴリー
• 大文字小文字
• 句読点

を揃えるようにしましょう。

段落

段落において最も重要なのは、書き出しです。
多くの人は二つ目の文を読み飛ばしてしまうので、一文目で読者の関心を引かなればなりません。

一つの段落には一つの主題を。主題を外れる文章は削ったり他の段落へ移すように。さらに、段落は短すぎても長すぎてもいけません。３〜５の文から構成するのがベターです。

また、良い段落というのは、読者に対して下の問いに答える段落を言います。

• 読者に伝えたいことは何か
• 読者がそれを知ることはなぜ重要なのか
• 読者はどのようにそれを使えるか、読者はどのようにそれを真だとわかるか

これらの問いに答えられるような段落構成を目指しましょう。

読者のことを考える

文章、段落と続いて今度は文章全体の構成についての話です。

良い文章というのは、読むのに必要な知識とスキルから読者の今の知識とスキルを引いたものだと言われています。言い換えると、読者が必要とする情報の中でまだ持っていない物を提供できる文章のことです。

つまり、読者の今の知識とスキルを把握していなければ、良い文章が書けません。文章を書く前に、読者を定義しましょう。

まず、どのような役割(ソフトウェアエンジニア、科学者、マネージャーなど)を持った人向けなのか。役割を定義することで、持っているスキルや知っている情報の範囲が想像できます。その際、どれぐらいの年月そのスキルを学んでいるかを考慮することも重要です。

続いて、読者が何を学ばないといけないのかをリスト化します。

そこまで考えてから文章を書くようにしましょう。
書くうえで気をつけないといけないのは、

• 読者の好奇心を満たすように書く
• 読者のボキャブラリーに合わせる
• 簡単な言葉を使う
• 熟語・慣用表現に気を付ける(別に国では通じないかもしれない)

以上の点です。
書き手の独りよがりな文章にならないよう、読者に向けて書くということを意識してください。

文書

最後は文書(ドキュメント)についてです。
文書を書き始めるときは、1ページ目に一番労力を割くこと。

• 何について書かれているのか
• 想定されている読者について
• 読者が既に知っていることは何か(読むための前提条件)
• これを読んで読者は何を得るのか

これらを初めにちゃんと書いておかなければいけません。

それができたら、プログラミングでクラスやメソッドを分けるように、文書を節に分けてください。大きな要素を先に、続いて細かい要素を足していきます。
そうしたら改めて声に出してみるなどして文章全体を読み直し、初めに書いた目的が達成できているかどうかしっかり確認しましょう。

さらに学ぶには

以上がテクニカルライティング講座１の内容でした。
もう一つ、テクニカルライティング講座２があるので、興味がある人はこちらも受講してみてください。
ちなみに２では、自分で文章を校正するときのやり方や、文章を構造化する方法、図示やサンプルコードの作り方などについて紹介されています。

Googleのスタイルガイドを読むのも勉強になるのでおすすめです。
LINE株式会社が出している日本語で書かれたテクニカルライティング講座もあるので、よかったらそちらも読んでみてください。