5. 明快な文

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

強い動詞を使う

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

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

• be 動詞: is, are, am, was, were など
• occur
• happen

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

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.

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

there is と there are を避ける

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

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

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

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

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

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

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

練習問題

次の文から 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 という名前のシャーディング関数がある。)

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

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

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

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