原文:https://developers.google.com/tech-writing
译文:https://t.co/UDlJUFEDt2?amp=1
翻译:陈皓(耗子叔)
第一部分
词性 | 定义 | 例 |
---|---|---|
Noun名词 | 人,地方,概念或事物 | Sam runs races.山姆赛跑。 |
Pronoun代词 | 替代另一个名词的名词 | Sam runs races. He likes to compete.山姆赛跑。他喜欢竞争。 |
Adjective形容词 | 修饰名词的单词或短语 | Sam wears blue shoes山姆穿蓝色的鞋子。 |
Verb动词 | 一个动作词或短语 | Sam runs races.山姆跑比赛。 |
Adverb副词 | 修饰动词,形容词或其他副词的单词或短语 | Sam runs slowly.山姆跑得慢。 |
Preposition介词 | 指定两个名词的位置关系的单词或短语 | Sam's sneakers are seldom on his shelf.山姆的运动鞋很少在他的架子上。 |
Conjunction连词 | 连接两个名词或短语的单词 | Sam's trophies and ribbons live only in his imagination.山姆的奖杯和缎带只存在于他的想象中。 |
Transition过渡 | 连接两个句子的单词或短语 | Sam runs races weekly. However, he finishes races weakly.山姆每周参加比赛。但是,他无力完成比赛。 |
名词代表人,地方或事物。朱迪(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.
动词是一个动作词或短语。当你您想要表示两个名词(一个行为者和一个目标)之间的关系时,该动词就起作用了。动词标识行为者对目标的作用。每个句子必须至少包含一个动词。例如,以下每个句子包含一个动词:
有些句子会包含多个动词,如:
根据时态和词缀变化,一个动词可以包含一个单词或多个单词。例如:
形容词修饰名词。例如,在下面的句子中,注意形容词如何修饰后面的名词:
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连接了“code”和“documentation”,而but连接了句子的前半部分和后半部分。
Natasha writes great internal code and documentation but seldom works on open-source projects.
Natasha 编写了大量的内部代码和文档,但是很少在开源项目上工作。
技术写作中最重要的过度词如下:
在下面的段落中,请注意过渡如何连接句子并使其上下文相关:
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 空指针错误一样在读者的脑海中造成错误的认知 。在许多情况下,你您应该简单地避免代词,而就直接重复使用该名词。但是,代词的效用有时会非常有用。
请考虑以下代词准则:
以下代词在技术文档中引起最大的混乱:
例如,在下面的句子中,它是指Python还是C ++?
Python是解释型语言,而C ++是编译型语言。它具有几乎类似邪教的追随者。
再举一个例子,它们 在接下来的句子中指的是什么?
将 Frambus 或 Carambola 与 HoobyScooby 或 BoiseFram 一起使用时要小心,因为它们的核心可能会导致意外的大量脱机。
考虑另外两个问题代词:
例如,在下面有歧义的句子中,“这” 可能是指Frambus,Foo或两者:
你您可以使用 Frambus 或 Foo 来计算导数。这 不是最佳的。
使用以下的战术来消除歧义这个和那个:
例如,以下两个句子中的任何一个都消除了前面的示例的歧义:
Overlapping functionality is not optimal.
This overlapping functionality is not optimal.
技术写作中的绝大多数句子都应该是主动语态。本单元教你您如何执行以下操作:
在主动的语态句子中,主语作用于目标。也就是说,主动语态句子遵循以下公式:
主动语态句=主语+动词+目标
被动的语态句子则反过来。即,被动语态语句通常遵循以下公式:
被动语态句=目标+动词+主语
例如,这是一个简短而主动语态句子:
The cat sat on the mat. 猫坐在垫子上。
相比之下,这是被动语态中的同一句话:
The mat was sat on by the cat. 垫子被猫坐着。
一些被动的语态句子省略了主语。例如:
The mat was sat on。
谁或什么坐在垫子上?一只猫?一只狗?霸王龙?读者只能猜测。技术文档中的好句子可以确定谁对谁做事。
被动动词通常具有以下公式:
passive verb = be 的形式 + 动词过去分词
尽管上述公式令人生畏,但实际上非常简单:
不幸的是,某些过去分词动词是不规则的;也就是说,过去分词形式不以后缀ed结尾。例如:
将be和过去分词的形式放在一起会产生被动动词,例如:
如果短语中包含一个主语,介词通常会跟在被动动词之后。(这个介词通常是帮助你辨别被动语态的关键线索)下面的例子结合了被动动词和介词:
将祈使动词开头的句子很容易错误地归为被动。一个祈使动词是一个命令。编号列表中的许多项目都以祈使动词开头。例如,以下列表中的“ Open”和“ Set ”都是祈使动词:
以祈使动词开头的句子通常采用主动语态,即使它们没有明确提及主语。相反,以命令式动词开头的句子暗示一个主语。这个隐含的主语就是“你”。
许多句子包含多个动词,其中有些是主动的,有些是被动的。例如,以下句子包含两个动词,两个动词均为被动语态:
完全转换为主动语态:
大部分时间使用主动态。谨慎使用被动语态。主动语态具有以下优点: