5. 明快な文

コメディのライターは最も面白い文章を追い求め、ホラーのライターは最も恐ろしい文章を追い求め、テクニカルライターは最も明快な文章を追い求めます。テクニカルライティングでは他のどんな規則よりも明快さが優先されます。この章では文を素晴らしく明快にするための方法をいくつか紹介します。

強い動詞を使う

多くのテクニカルライターは動詞こそが文の中で最も重要な部分だと信じています。正しい動詞を選びさえすれば、文の他の部分は自然に出来上がるということです。しかし残念なことに、少数の弱々しい動詞だけを使いまわすライターも中にはいます。これはまるで、しけたクラッカーとしおれたレタスで来客を連日もてなすようなものです。正しい動詞の選択には少し余計な時間がかかりますが、上手く選択できれば洗練された結果が得られます。

読者を気を引いて教育効果を高めるために、正確で、明確で、強い動詞を選びましょう。次に示すような不正確で、汎用的で、弱い動詞は避けるべきです:

文に含まれる弱い動詞を強めることで文意が際立っていることを次の例で確認してください:

弱い動詞 強い動詞

The error occurs when clicking the Submit button.

(Submit ボタンをクリックするときエラーが起こる。)

Clicking the Submit button triggers the error.

(Submit ボタンのクリックがエラーを引き起こす。)

This error message happens when...

(このエラーは ... のとき起こる。)

The system generates this error message when...

(... のときシステムがこのエラーを生成する。)

We are very careful to ensure...

(我々は ... を確認することを強く心掛けている。)

We carefully ensure...

(我々は ... を注意深く確認する。)

be 動詞を料理棚にある唯一の調味料であるかのように多用するライターが大勢います。いつもとは異なる動詞を振りかければ、文がより美味しそうに見えること請け合いです。ただ be 動詞が一番の選択肢である場合もあるので、文章から be 動詞を完全に取り除こうとする必要はありません。

汎用的な動詞が他の病気のサインであることもよくあります。病気とは次のようなものです:

練習問題

より明確な動詞を選ぶことで、次の文を明快にしてください。そのとき文の並び替えや単語の追加・修正・削除をして構いません。

  1. When a variable declaration doesn't have a datatype, a compiler error happens.

    (変数の宣言がデータ型を持っていない場合、コンパイルエラーが起こる。)

  2. Compiler errors occur when you leave off a semicolon at the end of a statement.

    (文の最後にセミコロンを置き忘れると、コンパイルエラーが起こる。)

  1. 考えられる解答をいくつか示します:

    • When a variable declaration doesn't specify a datatype, the compiler generates an error message.

      (変数の選言がデータ型を指定しないと、コンパイラはエラーメッセージを生成する。)

    • If you declare a variable but don't specify a datatype, the compiler generates an error message.

      (変数を宣言したときに データ型指定しないと、コンパイラはエラーメッセージを生成する。)

  2. 考えられる解答をいくつか示します:

    • Compilers issue errors when you omit a semicolon at the end of a statement.

      (文の終端のセミコロンを省くと、コンパイラはエラーを報告する。)

    • A missing semicolon at the end of a statement triggers compiler errors.

      (最後にセミコロンがない文はコンパイルエラーを引き起こす。)

there is と there are を避ける

There is や There are で始まる文は汎用的な名詞や汎用的な動詞が大好きです。そういったカップルによる汎用な結婚式は読者を退屈させるだけですから、真の主語と真の動詞を使って読者への心からの愛を示しましょう。

最も簡単な場合には、There is や There are (およびその後のいくつかの単語) を削除すればそれで済みます。例として次の文を考えます:

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

(現在の精度を保持する met_trick と呼ばれる変数がある。)

There is を削除すると、汎用的な主語がより良い主語に置き換わります。例えば、次の二つの文はどちらも上の文より明快です:

A variable named met_trick stores the current accuracy.

(met_trick という名前の変数が現在の精度を保持する。)

The met_trick variable stores the current accuracy.

(met_trick 変数が現在の精度を保持する。)

There is および There are で始まる文を直すために、真の主語と真の動詞を文の最後から最初に移動させる場合もあります。例えば次の文では、真の主語 you が文の後半で登場します:

There are two disturbing facts about Perl you should know.

(あなたが知っておくべき Perl に関する不穏な事実が二つある。)

主語を There are から You に置き換えれば文意がはっきりします:

You should know two disturbing facts about Perl.

(あなたは Perl に関する二つの不穏な事実を知っておくべきだ。)

他にも、筆者が真の主語や動詞を作る面倒を避けるために There is や There are で文を始めたという場合もあります。主語が無ければ、作れないか考えてください。例えば次の There is 文は誰がアップデートを受け取るかを明確に示していません:

There is no guarantee that the updates will be received in sequential order.

(アップデートが連続した順番で受け取られる保証はない。)

"There is" を意味の通る主語 (例えば clients) に置き換えれば、読者は文意を楽に読み取れます:

Clients might not receive the updates in sequential order.

(クライアントはアップデートを連続した順番で受け取らない可能性がある。)

練習問題

次の文から There is を削除し、必要なら単語の追加・変更・削除を行うことでより明快にしてください:

  1. There is a lot of overlap between X and Y.

    (X と Y にたくさんの重複がある。)

  2. There is no creator stack for the main thread.

    (メインスレッドに対するクリエイタースタックは存在しない。)

  3. There is a low-level, TensorFlow, Python interface to load a saved model.

    (保存されたモデルを読み込むための TensorFlow の低水準 Python インターフェースがある。)

  4. There is a sharding function named distribute that assigns keys.

    (キーを登録するための distribute という名前のシャーディング関数がある。)

  1. X and Y overlap a lot.

    (X と Y はかなり重複する。)

  2. The main thread does not provide a creator stack.

    (メインスレッドはクリエイタースタックを提供しない。)

  3. TensorFlow provides a low-level Python interface to load a saved model.

    (Tensorflow は保存されたモデルを読み込むための低水準 Python インターフェースを提供する。)

  4. The distribute sharding function assigns keys.

    シャーディング関数 distribute がキーを登録する。

文学的な形容詞や副詞をなるべく使わない

形容詞と副詞は小説と詩において素晴らしい活躍を見せます。形容詞があれば平坦でplainすさんだold草原は波打ちprodigal緑に溢れverdant生気のないlifeless髪はつやのあるsilky長く垂れたflowing髪となります。副詞があれば馬は何にも邪魔されずfreely一心不乱にmadly駆け回り、犬は大声でloudly獰猛にferociously吠えることができます。しかし残念ながら、技術文書の読者は形容詞や副詞を見て大声で獰猛に吠えることがあります。その理由は、彼らの基準では形容詞や副詞は定義が曖昧で主観的になりがちだからです。さらに悪いことに、形容詞や副詞を使うと技術文書が宣伝チラシのように見えてしまう危険性もあります。例えば、技術文書に次の文があったらどうでしょうか:

Setting this flag makes the application run screamingly fast.

(このフラグを設定すると、アプリケーションがあっと驚くほど速くなる。)

screamingly fast (あっと驚くほど速い) という言い回しは確かに読者の注意を引きますが、良い結果をもたらしません。技術文書の読者に伝えるべきなのは宣伝文句ではなく事実に基づいたデータです。曖昧な副詞と形容詞は主観的な数値データにリファクタリングしましょう。例を示します:

Setting this flag makes the application run 225-250% faster.

(このフラグを設定すると、アプリケーションが 225-250% 速くなる。)

この変更によって文から魅力が失われたでしょうか? ええ、多少は失われました。しかし改良によって文の正確さと信憑性が増しています。

注意: 文書を使った読者の教育 (テクニカルライティング) と文書を使った製品の宣伝・販売 (マーケティングライティング) を混同してはいけません。読者が教育を求めているなら、教育を提供してください。教育用の資料に宣伝・販売用の資料を混入させるべきではありません。