Words

我们深入研究了各种文档，发现最优秀的句子主要由单词组成。（译注：戏谑？）

定义新术语

编辑或写作时需要注意，一些术语对部分或者全部目标读者来说并不了解。如果你的文档有此种情况，可以使用以下两个技巧：

• 如果术语存在，可以链接到对应的术语解释出处（不要重复造轮子）。
• 如果文档本身就要介绍该术语，定义该术语，如果要介绍多个新术语，请将这些术语放到术语表。

术语命名一致性

若你在代码中把变量名字修改掉，你的代码无法编译通过。同样地，如果你文档中间将一个术语的名字作修改，你的想法无法“编译”（在读者的脑子里）。

所以准则就是：在文档中始终使用同一个不会混淆读者的单词或术语。若你已经将组件命名为 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 (or protobufs for short) provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

恰当使用首字母缩写

文档中或者段落中首次使用新的首字母缩写时，应当先将全称标出，并在全称后的括号内跟上缩写。同时，将全称和缩写粗体加黑。例如：

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.

在首次定义缩写后，就可以在文档后续位置使用该缩写了。例如：

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.

缩写还是全称？

当然，你可以恰当地介绍和使用缩写，但是应该要使用缩写吗？缩写当然可以将句子缩短。例如，TTN比Telekinetic Tactile Network少了2个单词。然而，缩写不过是一种形式的抽象， 读者必须在脑海里将新认识的缩写重新展开。例如，读者在脑海里将Telekinetic Tactile Network展开成TTN，所以看上去“更短”的缩写，实际上需要比全称花更多的时间来处理。

重度使用的缩写最终会发展出自己的“身份”。经过多次出现后，读者不用再将缩写展开成全称。例如，许多Web开发者已经忘了HTML全称是什么了。

以下为使用缩写的一些建议：

• 没有必要为使用量很小的术语建立缩写。
• 如果符合以下两种情况，请务必定义缩写：
  • 缩写比全称短的多。
  • 缩写在文档中会多次出现。

练习

修改下列段落。假设MapReduce在文档中第一次出现的位置是该段落，且MR是MapReduce的最佳缩写。

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.

令人混淆的代词

代词指代前文介绍的名词。这些代词就相当于程序代码中的指针。但就像指针一样，代词也会带来一些错误。错误地使用代词会在你读者的脑海里引入“空指针”。在很多情况下，你应当直接使用名词而不是使用其代词。然而，使用代词带来的好处有时会超出它引入的风险（就像这个句子一样）。

[!Note]

译注，原文是： However, the utility of a pronoun sometimes outweighs its risk (as in this sentence).

对代词的使用，有以下建议：

• 仅在介绍过名词后使用代词；绝不在名词出现前使用代词。
• 将代词与其指代的名词摆放得尽可能的近。一般来说，如果名词和代词间有5个其他单词，就需要考虑直接使用这个名词而不是使用代词。
• 如果名词和其代词间有其他名词，就直接使用名词，而不要使用代词。

It and they

在文档中以下代词最容易引起混淆：

• it
• they, them, and their

例如，在下面的句子中，It指代的是Python还是C++呢？

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

又例如，下面句子中their指代的是什么？

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

This and that

容易引起混淆的代词还有：

• this
• that

例如，在下面这个句子中，This可以指代user ID，也可以指向 running the process，也可以指向前面整句。

Running the process configures permissions and generates a user ID. This lets users authenticate to the app.

在使用this和that时，有一些小技巧可以避免混淆：

• 直接将this和that替换成对应的名词。
• 在this和that后马上使用对应的名词。

像下面的例句一样，根据实际情况使用代词或者明确的名词：

This user ID lets users authenticate.

The process of configuring permissions lets users authenticate.

The combination of permissions and a user ID lets users authenticate.

练习

下面例句中的代词的指向对象是不明确的，找出其所有可能的含义：

1. Aparna and Phil share responsibilities with Maysam and Karan and they are next on call.
2. You may import Carambola data via your configuration file or dynamically at run time. This may be a security risk.

Reference

原文：https://developers.google.com/tech-writing/one/words