作者：Kealan Parr
译者：周嘉晖
原文链接：www.freecodecamp.org/news/what-g…
译者按：技术写作由技术写作人员完成，是一个在专业场所编写和共享信息的过程。本文作者以第一人称视角，总结了他在参加完谷歌的技术写作课程之后的收获，例子生动，文章通俗易懂。无论你是中文技术写作者，还是打算以英语作为写作语言，相信这篇文章都能给你一些启发。
我最近花了差不多 4 个小时，完成了谷歌的一门技术写作课程，并且乐在其中。在课程过程中有一些小练习，你可以一边学习一边检验学习成果。
本文会简单介绍一下我从课程中学到了什么，我会总结出其中最精华的部分，希望阅读此文后，你能对这门课程有个大概的了解。
这门课程涵盖了一些英语的语法规则和语言学方面的知识。但我会在本文的前面部分把这些都解释一下，这样我们就在同一起跑线上啦。你不一定要是一名很厉害的作家才能完成这门课程，这门课程仅需要一点点英语写作能力。
让我们一起潜心学习吧。
引言
首先介绍一下本篇文章会涉及到的几个概念：
- 名词：名词用于给事物赋名，如：凯夫人、埃菲尔铁塔、经理。
- 代词：代词用来代替名词，如：我、你、我们、他们、他或它。
- 形容词：形容词用于描述名词，如：友好的凯夫人、生锈的埃菲尔铁塔、好经理。
- 动词：动词用来表示动作或状态，如：打架、奔跑、打字、吃。
- 副词：副词用来形容动词，如：激烈地打架、懦弱地奔跑、积极地打字、胆怯地吃东西。
写作要清楚明白
清楚，指的是你的观点呈现的清晰程度。在技术写作中，你的首要任务就是要把文章写清楚。
代词的使用
不管你什么时候使用代词，你要保证代词的指代是清楚的。使用代词很容易让读者产生困惑。比方说：
C++是一门很老的编程语言，JavaScript 也是一门很老的编程语言。不过我还是很喜欢这门语言。
蛤？你喜欢啥？是 C++还是 JavaScript？这里的代词指代不明确，有损文章的清晰程度。
应该这样使用代词：
C++是一门很老的编程语言，JavaScript 也是一门很老的编程语言。不过我还是很喜欢 C++这门语言。
一般来说，校对的时候，如果不清楚代词指的是什么，就用名词代替代词。使用这个或那个特别容易出现这个问题。你要确保每当你使用这些代词时，代词的指代都很明确。
习语的使用
习语是用来描述某件事情的常用词组。但有些习语对非本族语者来说毫无意义。由于习语仅流行于你所在的地区以或你所使用的语言，因此在你的技术写作中，你应该尽量避免使用这些习语。
其他人无法直接理解**在粥里绕来绕去（walking around the porridge，出自挪威语 gå rundt grøten，意思是说话啰嗦没有条理）、嚼肥肉（chewing the fat，意思是随便聊聊天）、给牛打气（inflating a cow，意思是吹牛）**的含义。写文章时，你只要把意思说清楚就好，尽量使用简单的比喻，不要使用习语。
写作要言简意赅
简洁是指你的写作有多简短，表达有多清晰。
一名优秀的软件工程师在打磨自己的作品时，删代码的时间和写代码的时间一样多。这在写作中也是一样的。一般来说，代码越短越好，因为：
- 让其他人更容易阅读
- 使代码更容易维护
- 额外的代码行增加了出现错误的可能性
所有这些观点也适用于技术写作。
想要简洁地传达你想说的话，并非一日之功，你必须认真地撰写文档。你甚至可能要对文档校对很多遍——但这是值得的。
更短的句子也会激励读者继续阅读，而一个巨长的段落有时会吓到读者。有些读者看到长达 1000 字的段落时，会直接从页面划走。
把“there be”句型删去
这是针对英语技术写作的，在英语中“there be”句型几乎都可以去掉，以便更简要地表达你的观点。“there be”句型一般都很笼统，让读者感到厌烦。我们可以重新组织句子。这里有一些例子：
- There is a lot of overlap between software and hardware.
- There are no multiple threads in JavaScript.
改良如下：
- Software and hardware have a lot of overlap.
- JavaScript does not have multiple threads.
少用形容词和副词
形容词和副词在小说、诗歌等描述性、创造性写作中使用较多。
谷歌给出的使用形容词的例子是把草变成青翠的繁茂的草，或者把听起来毫无生气的头发改成柔顺飘逸的头发。
问题是，副词和形容词的定义一般都太松散，它们会让你的技术写作听起来像营销文。
在生产模式下运行代码，使代码运行速度快得惊人。
与之相对的是：
在生产模式下运行该代码将带来 225%的性能提升。
希望你同意第二个句子更加精确和量化。
多用列表
当你有一个长句子，里面有很多元素的时候，你应该把它拆成一个列表。例如，如果你要列举某项技术的优点，你可以说，XX 技术是一个很好的选择，因为它：
- 轻量
- 快速
- 使用便捷
虽然这是一个简单的例子，但你应该能 get 到我想表达的意思。列表比一个过长的句子可读性强得多，使用列表能留住读者，也不会打断你的语流。
选对列表
如果你确实找到了使用列表的好地方，选对列表也很关键。你可以使用有序列表，像这样：
- 这是我的有序列表
- 是不是很漂亮？
你也可以使用无序列表，像这样：
- 这是我的无序列表
- 和上面不一样，但是也很炫酷
那你到底应该使用哪种列表呢？
在有序列表中，顺序很重要。尽量在每个数字的开头加上一个命令性的动词，让步骤说明更加清楚，比如一个菜谱：
- 打开烤箱。
- 烘烤蛋糕。
而无序列表适用于其他所有情况。
统一列表
在学会了用哪种列表之后，下一步将会帮助你在使用列表时，发挥其最大潜力，我们要做的就是让列表保持统一。统一是什么意思？
你列表中的每一项都应该：
- 语法和标点符号要统一
- 逻辑要统一（列表中的每一项都应该在逻辑上是列表的子项）
- 大小写要统一
让我们来举个反面教材：
- c++
- JAVASCRIPT?
- Rust!
- chocolate chip cookies
以上的三条规定都未被遵守。"chocolate chip cookies"（巧克力饼干）这一项在逻辑上不属于列表的子项；各个子项的大小写不统一；标点符号也不统一（读者搞不明白为什么 "JAVASCRIPT" 以“？”结尾，而 "Rust" 以“！”结尾。）
使用主动语态
句子一般由主语、宾语和动词组成。我们写几个句子试试：
我写了一个故事。
我是主语，故事是宾语，而写是动词。
我真的欣赏杰克的作品。
我是主语，作品是宾语，而欣赏是动词。
- 主语是做事情的人。
- 宾语是被做的事情。
- 动词是主语对宾语所做的事情。
上面的例子都用的是主动语态，因为主语对宾语发出动作。现在，让我们把上面这些例子改成被动语态：
这个故事由我撰写。
杰克的作品被我赏识。
使用主动语态，除了更加有力和直接之外，还有以下优点：
- 方便理解。每当人们读到被动语态的时候，都要费尽心思把被动语态转为主动语态。所以为了方便读者跳过这一步，直接阅读，我们用主动语态来写作。
- 读者更熟悉**主动语态。**主动语态对读者来说要熟悉得多，因为我们大多数时候遇到的句子都是主动语态的。
- 被动语态有时会导致达意不清，主语不明显，会迫使读者花费精力去猜测到底是谁干了什么事。
- 主动语态一般比被动语态简短。
通用的写作技巧
让我们来看看如何最大限度地优化一篇精心写出来的文章。
句子层面
开发人员都知道，要保持代码的单一职责原则。记住，写句子也是这样的原则。在一个句子中要清楚而简短地表达完一个意思，然后再写下一句。不要使用一大堆的and also this（这个也是）和 that too（那个也是），不要让我们的最后一句话很零碎。如果你最后一句话很零碎，就把and之后的话拆开单独成为最后一句。
段落层面
段落要有一个明确的开场白，解释段落的中心思想。
开场白应该包含：
- 你想表达的是什么？
- 为什么它很重要？
- 读者应当怎么运用这个知识？
让我们来举一个例子：
【是什么 ➡】garp()是一个返回一个数据集的平均数和中位数之间 Δ 的函数。【为什么 ➡】很多人都坚信平均数永远是真理。然而，平均数很容易受到几个非常大或非常小的数据点的影响。【怎么办 ➡】调用 garp()来帮助判断几个非常大或非常小的数据点是否对平均数影响太大。当 garp()的值比较小时，平均数更有意义。
行话及语境层面
行话是某一领域使用的专业术语。投资者们可能会谈论W8-BEN表格或SPAC。如果你的工作不属于这个领域，你根本不知道他们在讨论什么。在尽可能的情况下，去掉所有的行话和缩略语，并向读者解释难懂的地方。
尽量使你的写作通俗易懂，但仍要保持适当的复杂性（不要过度简化！）。如果你的文章很晦涩或复杂得让人难以理解，读者无法从中有所收获。
也不要预设你的读者都懂相关知识。如果你想谈论某件事情，要么解释一下，要么给个相关链接。有人把这称为知识的诅咒（Curse of Knowledge - 你懂太多了）。
要先预设你的读者知道的比你少，这样知识渊博的读者可以跳过他们已经知道的部分，新手读你的文章也不会一头雾水。
选词层面
英语是技术写作的主流语言，但英语不一定是读者的母语。尽量使用常用的、简单的英语单词。你 duck 不必高谈阔论你从多音节词中找到的亢奋，或者炫耀你的华丽词藻。
元信息
要写简介
写文章时，最好在一开始就简单解释一下你要讨论的内容。这可以帮助人们在阅读更多内容之前，了解你到底想讨论什么。
照顾读者
试着让你的文档合你读者的口味。当你在dev.to（文风偏专业的开发者社区）上写文章时，你可以用一种语调；而当你在 freeCodeCamp News（文风偏活泼的开发者社区）上写文章时，你可以用另一种语调。
撰写文档的时候要考虑受众。例如，如果你要向公司外更广泛的受众解释你公司的架构，你就得解释得更加透彻明白，因为他们了解的关于你公司的知识比你的同事少。
有时，你的读者甚至不是技术人员，你需要降低文章的难度，便于你的读者理解。
小结
让我们简要回顾一下刚刚所讨论的要点：
- 保持全文一致
- 避免使用含糊不清的代词
- 尽量使用主动语态
- 要言简意赅
- 一句话就只关注一个点
- 使用列表
- 删除多余字词
- 不要使用复杂的英语或行话
- 保持列表统一
- 开篇概述你所涉及的内容
- 照顾你文档的读者
- 在开始阶段确定你的写作要点
结语
在我完成谷歌技术写作课程之后，我收获了很多。我希望本文解释清楚了其中的一些概念。
在我写作的时候，我会试着把学到的建议用起来。希望这对你的写作也有所帮助。我在课程中学到了不少有用的写作原则，可以适用于我编写的文档或任何技术文章。
可以点击这里，找到我在本文中提到的课程。
如果你喜欢这篇文章并希望了解更多内容，我会在Twitter上分享我的文章。
课程链接：developers.google.com/tech-writin…
原作者 Twitter：twitter.com/kealanparr
欢迎关注「 字节前端 ByteFE 」
简历投递联系邮箱「 tech@bytedance.com 」
