3. 単語

我々が行った大規模なドキュメントの研究により、世界で最も優れた文は主に単語からなることが判明しました。

新しい単語や聞きなれない単語を定義する

執筆と推敲を行うときは、一部あるいは全ての対象読者にとって聞きなれない用語が使われていないかを意識してください。そのような用語がもしあれば、次のいずれかを使って対処します:

用語を一貫して使う

メソッドの途中で変数の名前を勝手に変えると、そのコードはコンパイルできません。同様に、ドキュメントの途中で同じものを指す用語を変えると、ユーザーはあなたが伝えたいことを (頭の中で) コンパイルできなくなります。

教訓: 曖昧さのない単語と用語を、ドキュメント全体で一貫して使うようにしましょう。あるコンポーネントを thingy と名付けたのなら、同じものを thingamabob と呼ばないでください。例えば、次の段落は誤って Protocol Buffers を protobufs に呼び変えています:

Protocol Buffers provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

(Protocol Buffers は独自の定義言語を提供する。...... 以上が protobufs がたくさんの品評会で優勝してきた理由である。)

このように残酷で制限の多いテクニカルライティングですが、少なくとも素晴らしいワークアラウンドが一つ存在します。それは、何らかの概念やプロダクトの長たらしい名前を導入するときに、その名前の省略形を明示するというものです。そうしておけば、以降ドキュメントでは省略形を利用できます。例えば、次の段落は問題ありません:

Protocol Buffers (or protobufs for short) provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

(Protocol Buffers (略して protobufs) は独自の定義言語を提供する。...... 以上が protobufs がたくさんの品評会で優勝してきた理由である。)

頭字語を正しく使う

聞きなれない頭字語をドキュメントあるいはセクションで初めて使うときは、最初に頭字語が表す用語を完全な形で書き、その後に頭字語を括弧に入れて書きます。さらに用語全体と頭字語の両方を太字にするべきです。例を示します:

This document is for engineers who are new to the Telekinetic Tactile Network (TTN) or need to understand how to order TTN replacement parts through finger motions.

(このドキュメントは Telekinetic Tactile Network (TTN) を初めて使うエンジニア、および TTN の交換部品を指の動きで注文する必要があるエンジニアのためのものである。)

このように用語を導入すれば、その後は頭字語を利用できます。次の例文に示す通りです:

If no cache entry exists, the Mixer calls the OttoGroup Server (OGS) to fetch Ottos for the request. The OGS is a repository that holds all servable Ottos. The OGS is organized in a logical tree structure, with a root node and two levels of leaf nodes. The OGS root forwards the request to the leaves and collects the responses.

(キャッシュエントリが存在しなければ、Mixer は OttoGroup Server (OGS) を呼んでリクエストのための Otto を要求する。OGS は処理を行える全ての Otto を保持するレポジトリである。OGS はルートノードと二つのレベルの葉ノードからなる論理木構造で表される。OGS ルートはリクエストを葉に転送し、レスポンスを収集する。)

ある用語の頭字語と完全な形を一つのドキュメントの中で混ぜて使うべきではありません。

頭字語を使うべきか?

これで頭字語の正しい導入方法が分かりましたが、そもそも頭字語を使うべきなのでしょうか? 頭字語が文を短くするのは確かです。例えば Telekinetic Tactile Network と書く代わりに TTN と書けば二語少なく書けます。しかし、頭字語が一つの抽象レイヤーであることは無視できません。読者は学んだばかりの頭字語を頭の中で完全な形に展開しなければならないのです。例えば二つ前の例文では、読者は TTN を Telekinetic Tactile Network へと置き換えて文章を読解します。そのため "短い" 頭字語を理解するには、完全な形を理解するよりも少しだけ長い時間が必要です。

一方で頻繁に使われる頭字語はそれ自身がアイデンティティを形成します。つまり同じ頭字語を何度も見かけると、読者は通常それを完全な形に展開しなくなります。例えばウェブ開発者の多くは HTML が何の略かを忘れているでしょう。

頭字語に関するガイドラインを示します:

練習問題

次の文章を修正してください。これはドキュメントの中で MapReduce という用語を使う最初の文章で、MapReduce を MR と省略すべきだとします。

Jeff Dean invented MapReduce in 1693, implementing the algorithm on a silicon-based computer fabricated from beach sand, wax-paper, a quill pen, and a toaster oven. This version of MR held several world performance records until 2014.

(ジェフ・ディーンは MapReduce を 1693 年に発明した。砂浜の砂・ワックスペーパー・羽ペン・トースターオーブンで作ったシリコン製コンピューターで MapReduce アルゴリズムを実装したのである。このバージョンの MR は 2014 年までいくつかのパフォーマンス世界記録を持っていた。)

(この文章はジョークであり、内容は正しくありません。)

可能なアプローチは二つあります。一つは MapReduce を頭字語 MR と結び付け、文中で MR を使うというものです:

Jeff Dean invented MapReduce (MR) in... This version of MR held several...

そうする代わりに、この短い文章で頭字語を定義するのは読者への負担が大きすぎると考えて、毎回 MapReduce と書くアプローチもあります:

Jeff Dean invented MapReduce in... This version of MapReduce held several...

ついでに言っておくと、より腕の立つテクニカルライターであれば "beach sand, wax-paper, a quill pen, and a toaster oven" の部分を箇条書きにするでしょう。箇条書きに関しては 7. リストとテーブル で説明します。

曖昧な代名詞を使わない

大部分の代名詞はそれまでに登場した名詞を指します。こういった代名詞はプログラミングにおけるポインタのようなものです。プログラミングにおけるポインタと同様に、代名詞ではエラーが起こりがちです。代名詞の使い方を間違えると、読者の頭の中で認識的なヌルポインタエラーが生じます。多くの場合で代名詞は避け、その代名詞が指す名詞を繰り返すべきです。しかし代名詞の効果がそのリスクを上回る場合もあります (ちょうどこの文のように)。

代名詞では次のガイドラインを使ってください:

if と they

次の代名詞は技術文書において最も深刻な混乱を引き起こします:

例えば次の文で、It が指すのは Python と C++ のどちらでしょうか?

Python is interpreted, while C++ is compiled. It has an almost cult-like following.

(Python はインタープリタで実行され、C++ はコンパイルされてから実行される。それはカルトじみた支持者を持つ。)

別の例として、次の文の their が指すのは何でしょうか?

Be careful when using Frambus or Carambola with HoobyScooby or BoiseFram because a bug in their core may cause accidental mass unfriending.

(Frambus または Carambola を HoobyScooby または BoiseFram と共に使うときには注意が必要となる。なぜなら、それらのコアにあるバグが誤って大量のフレンド解除を引き起こす可能性があるためだ。)

this と that

次の代名詞にも注意が必要です:

例えば、次の曖昧な文において、This は Frambus と Foo のどちらかまたは両方を参照できます:

You may use either Frambus or Foo to calculate derivatives. This is not optimal.

(微分係数の計算には Frambus または Foo を利用できる。これは最適でない。)

thisthat の曖昧さは次の方法のいずれかを使って取り除きます:

例えば、直前の例では次の文を使うと曖昧でなくなります:

Overlapping functionality is not optimal.

(機能が重複することは最適でない。)

This overlapping functionality is not optimal.

(このように機能が重複することは最適でない。)

練習問題

次の文章に含まれる曖昧な代名詞の意味として考えられるものを全て説明してください:

  1. Aparna and Phil share responsibilities with Maysam and Karan and they are the next ones on call.

    (アパーナとフィルはメイザムとカランと同じ責務を持っている。彼らは二番目の人員として待機している)

  2. You may import Carambola data via your configuration file or dynamically at run time. This may be a security risk.

    (Carambola データは設定ファイルからインポートすることも、実行時に動的にインポートすることもできる。これはセキュリティリスクとなる可能性がある。)

  1. 代名詞 they は次のいずれかを意味できます:

    • Aparna と Phil
    • Maysam と Karan
    • Aparna と Phil と Maysam と Karan
  2. 代名詞 this は次のいずれかを意味できます:
    • 設定ファイルから設定をインポートすること
    • 実行時に設定を動的にインポートすること
    • この二つ両方