简介

《Google 技术写作》是针对英文写作提出的方法论，但有些内容同样适用于中文写作。本文对该文档的技术写作要点部分进行了一个简单总结，供自己学习和期望提高技术写作能力的同学快速了解基本写作技巧。如需详细阅读，请点击原链接。

技术写作的九个技巧

1. 始终使用同一术语

定义了一个术语，在表达相同意思时就应该使用同一术语。

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

2. 正确使用首字符缩写词，首字母缩写词的使用准则：

• 请定义同时满足以下两个条件的首字母缩写词，否则不要考虑使用缩写词

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

3. 消除代词歧义

像编程中的指针一样 ，代词往往会引入错误。代词使用不当会就像程序中的 NULL 空指针错误一样在读 者的脑海中造成错误的认知 。在许多情况下，你应该简单地避免代词，而直接重复使用该名词。但是，代词的效用有时会非常有用。

请考虑以下代词使用准则：

• 引入名词后才使用代词；在介绍名词之前，切勿使用代词。
• 代词应尽可能靠近指称名词。根据经验，如果将名词与代词分隔开的单词超过 五个，请考虑重复使用名词，而不要使用代词。
• 如果在名词和代词之间引入第二个名词，请重复使用名词，而不要使用代词。

4. 技术写作中的绝大多数句子都应该是主动语态

主动语态具有以下优点：

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

5. 清晰的句子

喜剧作家寻求最有趣的结果，恐怖作家寻求最恐怖的结果，技术作家寻求最清晰的结 果。

• 选择强动词：选择正确的动词，句子的其余部分都会顺理成章。

6. 简短的句子

• 一句话只聚焦在一个想法

下面的反面例子强行将两个想法粘贴在一起：

萨曼莎（Samantha）是一位出色的编码员，她编写了大量测试。

使用句号来分隔两个独立的思想。例如：

萨曼莎（Samantha）是一位出色的编码员。她写了大量的测试。

• 将长句子转换为列表

  • 推荐在有序列表中，列表项使用动词开头，例如打开或启动

7. 一个段落聚焦一个主题

一个段落应代表一个独立的逻辑单元。将每个段落限制为当前主题。不要描述将来的 话题会发生什么或过去的话题会发生什么。当我们要修改编辑时，一定要毫不犹豫地删 除（或移至另一段）任何与当前主题无直接关联的句子。

• 段落不要太长或太短
• 回答what，why 以及 how

(What) 该 grap() 函数返回一个数据集的平均值和中位数之间的增量。(What) (Why) 许多人毫不怀疑地相信，平均值之道总是真理。但是，平均 值很容易受到几个非常大或非常小的数据点的影响。(Why) (How) 调用garp()可以帮助确定是否有几个非常大或非常小的数据点对均值的影响太大。相比 较高的grap()值，较小的grap()值说明平均值更有意义。(How)

8. 写一个精彩的开头句

开头句子是任何段落中最重要的句子。忙碌的读者只关注开头的句子，有时会跳过后面 的句子。因此，将精力集中在开头句上。

好的开头句确立了段落的中心点。即每个段落尽量采取一种总-分 的写法。

9. 使用 Markdown 来书写你的文章

参考资料

[1]. Google 技术写作