定义新术语或不熟悉的术语

在写作或编辑时，识别那些目标受众可能不熟悉的术语。当你发现此类术语时，请采取以下两种策略之一：

  • 如果该术语已经存在，请链接到现有的具体解释。（不要重新发明轮子）
  • 如果你的文档中引入了该术语，请定义该术语。如果你的文档引入了许多术语，请将定义收集到词汇表中。

    始终使用术语

    如果在方法中途更改变量的名称，则代码将无法编译。同样，如果你在文档中间重命名术语，则你的想法将无法编译（在用户头脑中）。
    修养：在整个文档中始终使用相同的明确词或术语。一旦你将某个组件命名为thingy之后，不要将其重命名为 thingamabob。例如，以下段落错误地将 Protocol Buffers 重命名为 protobufs：
    Protocol Buffer 提供了自己的定义语言。…………。这就是 protobufs 赢得如此众多县博览会的原因。
    是的，技术写作是残酷和充满限制的，但是至少技术写作提供了一个很好的解决方法。即，当引入冗长的概念名称或产品名称时，你也可以指定该名称的缩写形式。然后，你可以在整个文档中使用该简称。例如，以下段落很好：
    Protocol Buffer（或简称 protobuf）提供了自己的定义语言。…… 这就是 protobuf 赢得如此众多县博览会的原因。

    正确使用首字母缩写词

    在文档或章节中首次使用不熟悉的首字母缩写词时，请拼写完整的术语，然后将首字母缩写词放在括号中。拼写版本和首字母缩写用黑体字标出。例如：
    本文档适用于远程触觉网络 Telekinetic Tactile Network（TTN）的新手或需要了解如何通过手指运动订购TTN替换零件的工程师 。

然后可以使用首字母缩略词，如以下示例所示：
如果不存在缓存条目，则混合器将调用 OttoGroup Server（OGS）来为请求获取Ottos。OGS是一个存放所有可使用的Otto的存储库。OGS以逻辑树结构组织，具有一个根节点和两个级别的叶节点。OGS根将请求转发到叶子并收集响应。
另外，不要在同一文档中的首字母缩写词和扩展版本之间来回切换。

使用首字母缩写词还是完整术语？

当然，你可以正确地引入和使用首字母缩写词，但是你真的要使用首字母缩写词吗？好吧，首字母缩略词确实减少了句子的大小。例如，TTN 比Telekinetic Tactile Network 短很多。但是，首字母缩略词实际上只是抽象层。读者必须在头脑中将最近学到的首字母缩略词扩展到整个术语。例如，读者在脑海中将 TTN 转换为 Telekinetic Tactile Network，因此“较短”的首字母缩略词实际上要比整个术语花费更长的时间。
大量使用的首字母缩写词基本上会变成另外一个新词。在出现许多情况后，读者通常停止将首字母缩略词展开成具体的单词。例如，许多Web开发人员已经忘记了HTML这个术语展开后是什么。
这是首字母缩写词的准则：

  • 不要定义只会使用几次的首字母缩写词。

  • 请定义同时满足以下两个条件的首字母缩写词：

    • 该首字母缩写词明显短于整个术语。
    • 该首字母缩写词在文档中很多次出现。

      消除代词歧义

      许多代词指向先前引入的名词。这种代词类似于编程中的指针。像编程中的指针一样，代词往往会引入错误。代词使用不当会就像程序中的 nullptr 空指针错误一样在读者的脑海中造成错误的认知 。在许多情况下，你应该简单地避免代词，而就直接重复使用该名词。但是，代词的效用有时会非常有用。
      请考虑以下代词准则：

  • 引入名词后才使用代词；在介绍名词之前，切勿使用代词。

  • 代词应尽可能靠近指称名词。根据经验，如果将名词与代词分隔开的单词超过五个，请考虑重复使用名词，而不要使用代词。

  • 如果在名词和代词之间引入第二个名词，请重复使用名词，而不要使用代词。

    it 和 they

    以下代词在技术文档中引起最大的混乱：

  • it

  • they，them 和 their

例如，在下面的句子中，它是指Python还是C ++？
Python是解释型语言，而C ++是编译型语言。它具有几乎类似邪教的追随者。
再举一个例子，它们 在接下来的句子中指的是什么？
将 Frambus 或 Carambola 与 HoobyScooby 或 BoiseFram 一起使用时要小心，因为它们的核心可能会导致意外的大量脱机。

this 和 that

考虑另外两个问题代词：

  • this
  • that

例如，在下面有歧义的句子中，“这” 可能是指Frambus，Foo或两者：
你可以使用 Frambus 或 Foo 来计算导数。这 不是最佳的。
使用以下的战术来消除歧义这个和那个：

  • 将 this 或 that 替换为相关的名词。
  • 在 this 或 that 后马上使用那个名词。

例如，以下两个句子中的任何一个都消除了前面的示例的歧义：
Overlapping functionality is not optimal.
This overlapping functionality is not optimal.