新しい用語を定義する
文章を書き進めていくに従い、読者にとって馴染みのない用語を用いる機会が出てきます。
その場合には、次のいずれかの方針を用います。
- 既存の用語の場合、脚注や巻末の用語集に解説を記載します。Webページなどの場合は、外部の説明文にリンクを作るのも良いでしょう。
- 書いている文章がそれらの用語を紹介する場合、本文中にそれらの意味、スコープや用法を定義します。
用語の使い方を首尾一貫する
プログラム中にある要素を格納する変数名を変えた場合にはコンパイルできないように、文章の途中で用語の名前を変えると、読者の理解に混乱を起こします。
同じ対象を表す用語は文章を通じて同じにしなければなりません。
例えば、あるコンポーネントをAAAと名付けたら、途中でaaaにしてはいけません。
また、「サーバー」を「サーバ」のように長母音を省略するなども、名前の変更と見なされますので避けてください。
例えば製品名や概念などで用語が長くなる場合には、適切な省略語を用いる事が可能です。
この場合には、以降の文章中では原則として省略語のみを用いるようにしてください。
| 例文： 人工知能(AI)は様々な産業分野で応用されている。例えば、部品の生産工場ではAIを用いて欠陥品の識別を行っている。 |
頭字語を適切に用いる
技術文書では、複数の単語からなる長い名称の場合に頭字語が用いられる場合があります。
この場合にはフルバージョンの名前と頭字語を並べて書きます。
| 高速フーリエ変換（英：Fast Fourier Transform , FFT）は、離散フーリエ変換（英: Discrete Fourier Transform, DFT）を計算機上で高速に計算するアルゴリズムである。クーリー–テューキー型アルゴリズムは、代表的なFFTアルゴリズムである。 |
頭字語を定義した以降は、フルバージョンの名前か頭字語のいずれか一方で記述していきます。
ある文ではフルバージョンの名前を使った場合、別の文では頭字語を使って混在させないようにしてください。
また頭字語を用いると文章を短くできますが、頭字語はある種の抽象化でもあり、馴染みのない頭字語を読者は頭の中でオリジナルのフルバージョンの名前に置き換えている場合もあります。
この場合には文章の理解に余計な負担をかけていることになります。
逆に利用頻度の高い頭字語の場合には、そちらの方が市民権を得ている場合もあります。例えば、先の例に出てきたFFTも技術者の間では普通に通用しますし、HTMLなども頭の中でいちいちHyper Text Markup Languageと翻訳する人の方が珍しいでしょう。最近では機械学習=Machine LearningをMLと略す文章もよく見かけます。こちらは読者層によってはMailing Listと混乱する場合もありますので、文脈や想定読者層に合わせて使い分けてください。
代名詞の曖昧さを避ける
「それは」、「それらは」等の代名詞を用いた表現では、指し示す対象が曖昧な場合に、読者の頭の中では混乱が生じます。
さながら、代名詞がポインターの役割を果たすとすれば、null pointer exceptionでプログラムが停止するようなものです。
このリスクを避けるには、代名詞を使う代わりに元の名詞を使えば良いのですが、冗長になって読みにくくなる場合もあります。
次のようなガイドラインを考慮してください
- 対象の名詞が出てくるまで、代名詞を使わない
- 代名詞は対象の名詞に出来るだけ近いところで用いる
- 対象の単語と代名詞の間に、別の名詞が登場した場合、代名詞の代わりに元の名詞を使う
- 誤解された場合に致命的な結果が想定できる場合（例えば手順書のコマンド名など）、代名詞の代わりに元の名詞を使う。