原文:How Google's Technical Writing Course Helped Me Become a Better Writer,作者:Kealan Parr

谷歌有一门技术写作课程,我最近刚学完这个课程并且非常喜欢。课程大约需要4个小时,并且配套有一些实操练习,可以检测自己的学习效果。

我将简要说明我学完这门课程后学到了什么,同时也会总结出其中最好的部分,这样你就可以了解这门课所涉及的大概内容。

我会说到一些英语的语法规则和语言学内容,但我都会提前做解释,这样,可以保证我们的理解是一致的。要完成这门课程,你只需要有“一点点英语写作能力”就好,而“不必特别擅长写作”。

开始进入主题吧。

前言

首先定义本文将会使用到的一些术语:

  • 名词 用于称呼某物。例如凯夫人埃菲尔铁塔或者经理
  • 代词 用于代替名词。例如你/你们我们他们/她们/它们
  • 形容词 用于修饰名词。例如友好的凯夫人、锈迹斑斑的埃菲尔铁塔或者不错的经理。
  • 动词 表示动作或状态的词,例如打架奔跑打字
  • 副词 用于修饰动词。例如打斗猛烈怯懦地奔跑、一个劲儿地打字和胆怯地吃东西。

清晰

清晰是说你写作中的观点是否清晰。技术写作的首要关键就是清晰。

代词用法

使用代词时,一定要确保代指事物是清晰明确的,不然很容易让读者混淆。例如这样:

C++是一门相当古老的语言,但JavaScript也有些年代了。不过,我还是喜欢它。

啊?你到底喜欢什么?C++还是JavaScript?这里的代词并不明晰。

要明晰代词的用法,可以像这样:

C++是一门相当古老的语言,但JavaScript也有些年代了。我真的喜欢C++。

一般来说,在校对时,如果不清楚代词指的是什么,那就用名词而不要用代词。这个或者那个特别容易引起歧义。无论什么时候用这类代词,确保指代明确。

习语

习语是描述事物时常用的短语。但有些习语并不适用于世界各地的读者,因为习语是你的地区/语言所特有的,尽量避免在技术写作中使用习语。

没有人能一来就理解围着粥边转、咀嚼肥肉或者给牛充气这些习语隐含的喻义。直白说你的意思就好了,尽量使用简单的类比,不用习语。

表达简洁

简洁度是指你写作表达的简短清晰程度。

优秀的软件工程师在优化工作时,会在编写代码上花尽可能多的时间去删除代码。写作同样如此。通常,

  • 代码越短越易于他人阅读
  • 代码越短越易于维护
  • 额外的代码行会引入额外的问题

所有这些要点也都适用于你的技术写作。

有时,打磨文章和精炼表达需要花时间,你必须真正地对文档精雕细琢。甚至你可能需要校对多次——但,这都是值得的。

较短的句子也能鼓励读者继续阅读。一大长段太吓人了吧?长段有时会让读者望而生畏。有的读者看到一个段落足有上千字,就会直接退出页面。

删除“在(某地)存在一个”和“在(某地)存在多个”

在写作过程中,“在(某地)存在一个(there is)”和“在(某地)存在多个(there are)”几乎都可以删掉,让你的观点更简洁。

这2个说法通常很泛在并且让读者感到厌烦。改写一下句子吧。以下是一些示例:

  • 在软件和硬件之间有很多重叠的地方。
  • 在JavaScript中不存在多线程。

我希望你也认同改后的句子读起来更好:

  • 软件和硬件有很多重叠的地方。
  • JavaScript没有多线程。

尽量少用形容词和副词

形容词和副词常用于小说和诗歌等描述类和创造类写作中。

谷歌技术写作课程中,举的例子是把“”改写为“青翠茂密的草”或者把听起来毫无生机的“头发”改写为“丝滑飘逸的头发”。

问题在于形容词副词的定义常常很粗略,它们可能会让技术写作看起来像是营销写作。

在生产模式中,代码运行速度极其快。

对比:

在生产模式中,代码运行效率将提升225%。

希望你也认同改写后的句子更精准且可量化。

使用列表

一个长句里包含很多元素时,你可以把长句拆成列表形式。例如,如果你要列举某项技术的好处,你可以说,X是一个不错的选择,因为:

  • 它是轻量级的
  • 它速度很快
  • 它容易使用

虽然这是一个简单的例子,但你理解我的意思了吧。现在这样比一个冗长的句子更易读,你也不会失去你的读者或者流量。

正确使用列表

如果你觉得某个地方确实可以使用列表,那正确使用很重要。可以像这样使用有序列表:

  1. 这是我的有序列表
  2. 它是不是很美观?

或者也可以像这样使用无序列表:

  • 这是我的无序列表
  • 看起来不一样,但仍然很酷

所以你应该使用哪一种列表呢?

像食谱这种顺序很重要的话,那就使用有序列表。也可以试着在每个序号后面使用一个命令式动词打头,强调列表中的步骤说明:

  1. 打开烤箱。
  2. 烘烤蛋糕。

无序列表适用于其它所有内容。

列表结构保持平行

现在你应该能够正确使用列表了。下一步,要充分利用列表功能,你需要让每个列表的结构平行。什么意思呢?

所有列表项目应保持相同的:

  • 语法和标点符号
  • 逻辑分类(所有列表项目逻辑上属于同类别)
  • 大小写规则

举一个错误的例子:

  • c++
  • JAVASCRIPT?
  • Rust!
  • 巧克力片饼干(chocolate chip cookies)

这个例子违反了上述所有规则。“巧克力饼干”在逻辑上不属于这个列表、每个元素的大小写不一致、标点符号的使用未统一(不清楚为什么“JAVASCRIPT”以“?”结束,而“Rust”以“!”结束)。

使用主动句

句子通常由主语宾语谓语组成。用几个句子来测试一下吧:

我写了一个故事。

是主语,故事是宾语,是谓语。

我真的羡慕杰克的工作。

主语,杰克是宾语,羡慕是谓语。

  • 主语是指做事情的人或物。
  • 宾语是指被做的事情。
  • 谓语是指主语对宾语发出的动作。

上述所有例子使用的是主动句,因为是主语对宾语做了动作。所以我们把这些例子改为被动句的话,那就是:

故事是由我写的。

杰克的工作引起了我的羡慕。(或者杰克的工作被我羡慕。)

你应该使用主动句,因为除了表达会更加有力和直接以外,

  • 也更易于阅读。人们读到被动句时,还必须付出一些心力,将被动句转为主动句。所以,为了便于阅读,写作时使用主动句而不要用被动句。
  • 读者更熟悉主动句,因为我们大多阅读的都是主动句。
  • 被动句有时会迫使读者去猜测,这个句子里谁做了什么,让人费解。
  • 主动句一般比被动句短。

通用写作技巧

让我们看看如何最大程度地优化每个部分来写出一篇精美的文章吧。

句子

开发人员熟悉代码编写的单一性原则,这个原则在写句子时也同样适用。

一个观点表达简明清晰后,再写下一个句子。不要有大量的和这个和那个甚至可以把最后一句进行拆分。如果你后面写句子,记得把每个后面的文字拆开,单独成句。

段落

段落应该有一个明确的开场白句子,解释本段落的中心思想。

你也应该清楚地回答以下问题:

  • 你想表达的是什么?
  • 为什么这很重要?
  • 读者应该如何利用这些知识?

我们可以举个例子,应用上述所有技巧。

garp()函数返回一个数据集的平均数和中位数之间的差值。很多人坚信不疑的是平均数总是不会错的。然而,平均数很容易受到几个非常大或非常小的数据点的影响。

调用garp()来辅助确定几个非常大或非常小的数据点是否对平均数影响过大。garp()值相对较小时,平均数更可取。

行话和认知语境

行话是特定领域使用的专门术语。

投资者可能会谈论W8-BEN表格或者SPAC。但如果你是圈外人,就不知道他们在谈论什么。

尽可能删除所有的行话和缩略语,只给出简要解释就好。

尽量让你的文章平实简单,但对于你讨论的内容仍然需要解释到位(不能过于简化!)。如果你写得有难度或者复杂让人难以理解,那它就帮不到任何人。

不要对认知语境做假定。如果你想谈论某件事,要么解释它,要么尝试给一个相关的优质链接。有些人把预先假定对方的认知语境称为知识的诅咒

要假装读者比你知道得少,这样有经验的读者可以直接略过他们已经知道的部分,而萌新也不会感到困惑。

遣词用字

英语是技术写作的主要语言,却不一定是读者的母语。尽量坚持使用常用的、简单的英语词汇。

不必使用那些多音节大词,那样会显得华而不实

元信息

写一个简介

写作之前,在开头简要说明你要写的内容。这有助于读者往下阅读之前清楚知道你即将讨论的内容。

根据读者不同而调整所写内容

试着让你的文档适合对应的读者。在 dev.to 上,你可能用一种写作方式;在freeCodeCamp文章专栏上,你可能会用另一种写作方式。

根据读者不同而调整所写内容。例如,如果你要向更多读者解释你公司的架构,因为你的读者不像你同事知道那么多,你必须把事情解释得更透彻。

有时,你甚至可能不是为技术人员写作,那就需要用一种不那么复杂的方式来解释事情,帮助读者理解。

总结

简要概述一下本文涵盖的内容:

  • 通篇结构试着保持一致
  • 避免使用模棱两可的代词
  • 多用主动句
  • 表达简洁
  • 每个句子写一个观点
  • 使用列表
  • 注意删除不必要的词语
  • 不要使用复杂的英语或者行话
  • 保持列表结构平行
  • 段落首句为概述句
  • 根据读者对象确定写作内容
  • 文章开篇点明主旨

结语

我希望这篇文章解释清楚了那些我从谷歌技术写作课程中学到的有用概念。

我打算尝试挑选一些课程里给到建议的相关内容,将其应用于我的写作中,我希望这也能帮到你。在这里我发现了一些对我有用的规则,这些规则可以用于我制作的文档或任何技术写作内容。

文章中提到的谷歌技术写作课程可以在这里找到。

如果你喜欢这篇文章,并且还想看更多,可以在推特看看我的写作分享。