Google 技术写作教程

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

译文：https://t.co/UDlJUFEDt2?amp=1

翻译：陈皓(耗子叔)

第一部分

语法

名词

名词代表人，地方或事物。朱迪（Judy），南极洲（Antarctica）和 锤子（Hammer）都是名词，无形的概念（例如健壮性 robustness 和完美性 perfection ）也是如此。例如，我们在下面的示例中加粗了名词：

In the framework, an object must copy any underlying values that the object wants to change. The protos in the codebase are huge, so copying the protos is unacceptably expensive.

代词

代词是一个间接层，它指向或替代了其他名词或句子。例如：Janet writes great code. She is a senior staff engineer. 示例中，第一句话将Janet建立为名词。第二句用代词“ She”代替名词“Janet”。

在以下示例中，代词This代替了它前面的整个句子：

Most applications aren't sufficiently tested. This is poor engineering.

动词

动词是一个动作词或短语。当你您想要表示两个名词（一个行为者和一个目标）之间的关系时，该动词就起作用了。动词标识行为者对目标的作用。每个句子必须至少包含一个动词。例如，以下每个句子包含一个动词：

• Sakai prefers pasta. 酒井法子喜欢面食。
• Rick likes the ocean. 瑞克喜欢大海。
• Smurfs are blue. 蓝精灵是蓝色的。
• Jess suffers from allergies. 杰西有过敏症。

有些句子会包含多个动词，如：

• Nala suffers from allergies and sneezes constantly. 娜娜过敏，经常打喷嚏。
• Chung likes snacks to eat while riding the train. Chung喜欢在火车上吃零食。

根据时态和词缀变化，一个动词可以包含一个单词或多个单词。例如：

• Tina was eating breakfast a few hours ago. 蒂娜几小时前正在吃早餐。
• Tina is eating lunch right now. 蒂娜现在在吃午餐。
• Tina will eat dinner tonight at 7:00. 蒂娜将在7点吃晚餐。

形容词和副词

形容词修饰名词。例如，在下面的句子中，注意形容词如何修饰后面的名词：

Tom likes red balloons. He prepares delicious food. He fixed eight bugs at work.

大多数副词修饰动词。例如，注意下面句子中的副词是如何(有效地)修饰动词的：

Jane efficiently fixes bugs.

副词不一定紧挨着动词。例如，在下面的句子中，副词(effective)与动词(fixes)相距两个单词

Jane fixes bugs efficiently.

副词也可以修饰形容词或其他副词。

连词和过渡

连词连接句子中的短语或名词；过渡连接句子本身。最重要的连词如下：

• and
• but
• or

例如，在下面的句子中，and连接了“code”和“documentation”，而but连接了句子的前半部分和后半部分。

Natasha writes great internal code and documentation but seldom works on open-source projects.

Natasha 编写了大量的内部代码和文档，但是很少在开源项目上工作。

技术写作中最重要的过度词如下：

• however
• therefore
• for example

在下面的段落中，请注意过渡如何连接句子并使其上下文相关：

Juan is a wonderful coder. However, he rarely writes sufficient tests. For example, Juan coded a 5,000 line FFT package that contained only a single 10-line unit test.

Juan 是一个出色的程序员。然而，他很少编写足够的测试。例如，Juan编码了一个5000行的FFT包，却只包含一个10行的单元测试。

单词

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

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

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

始终使用术语

如果在方法中途更改变量的名称，则代码将无法编译。同样，如果你您在文档中间重命名术语，则你您的想法将无法编译（在用户头脑中）。

修养：在整个文档中始终使用相同的明确词或术语。一旦你将某个组件命名为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.

主动语态与被动语态

技术写作中的绝大多数句子都应该是主动语态。本单元教你您如何执行以下操作：

• 区分被动语态和主动语态。
• 将被动语态转换为主动语态，因为主动语态通常更清晰。

用简单的句子区分主动语态和被动语态

在主动的语态句子中，主语作用于目标。也就是说，主动语态句子遵循以下公式：

主动语态句=主语 动词 目标

被动的语态句子则反过来。即，被动语态语句通常遵循以下公式：

被动语态句=目标 动词 主语

主动语态示例

例如，这是一个简短而主动语态句子：

The cat sat on the mat. 猫坐在垫子上。

• 主语：The cat
• 动词：sat
• 目标：the mat

被动语态示例

相比之下，这是被动语态中的同一句话：

The mat was sat on by the cat. 垫子被猫坐着。

• 目标：The mat
• 被动动词：was sat
• 主语：the cat

一些被动的语态句子省略了主语。例如：

The mat was sat on。

• 主语：不明
• 被动动词：was sat
• 目标：the mat

谁或什么坐在垫子上？一只猫？一只狗？霸王龙？读者只能猜测。技术文档中的好句子可以确定谁对谁做事。

识别被动动词

被动动词通常具有以下公式：

passive verb = be 的形式 动词过去分词

尽管上述公式令人生畏，但实际上非常简单：

• be 在一个被动动词中通常是下列词语之一：
  • is / are
  • was / were
• past participle verb 过去分词动词 通常是一个普通的动词加上过去式的后缀 ed。例如，以下是过去分词动词：
  • interpreted
  • generated
  • formed

不幸的是，某些过去分词动词是不规则的；也就是说，过去分词形式不以后缀ed结尾。例如：

• sat
• known
• frozen

将be和过去分词的形式放在一起会产生被动动词，例如：

• was interpreted
• is generated
• was formed
• is frozen

如果短语中包含一个主语，介词通常会跟在被动动词之后。(这个介词通常是帮助你辨别被动语态的关键线索)下面的例子结合了被动动词和介词：

• was interpreted as 被解释为
• is generated by 由……生成
• was formed by 由……形成
• is frozen by 被……冻结

祈使动词通常是主动的

将祈使动词开头的句子很容易错误地归为被动。一个祈使动词是一个命令。编号列表中的许多项目都以祈使动词开头。例如，以下列表中的“ Open”和“ Set ”都是祈使动词：

1. Open the configuration file.
2. Set the Frombus variable to False.

以祈使动词开头的句子通常采用主动语态，即使它们没有明确提及主语。相反，以命令式动词开头的句子暗示一个主语。这个隐含的主语就是“你”。

用更复杂的句子区分主动语态和被动语态

许多句子包含多个动词，其中有些是主动的，有些是被动的。例如，以下句子包含两个动词，两个动词均为被动语态：

完全转换为主动语态：

首选主动语态而不是被动语态

大部分时间使用主动态。谨慎使用被动语态。主动语态具有以下优点：

• 大多数读者会在心理上将被动语态转换为主动语态。为什么要使读者的处理时间更长？通过坚持主动语态，读者可以跳过预处理阶段，直接进入编译阶段。
• 被动语态会使你您的想法模糊不清，使他们的句子变得无聊。被动语态间接报告操作。
• 一些被动语态的句子完全忽略了主语，这迫使读者猜测主语是谁。
• 主动语态通常比被动语态更短。