text: 'use strict';(function(){const indexCfg={cache:true};indexCfg.doc={id:'id',field:['title','content'],store:['title','href','section'],};const index=FlexSearch.create('balance',indexCfg);window.bookSearchIndex=index;index.add({'id':0,'href':'/tech-writing/docs/one/active-voice/','title':"Active Voice",'section':"One",'content':"1.2 主动语态 vs. 被动语态 #   预计阅读时间：15 分钟\n  译注：本节主要针对英语内容，读者可以选择性阅读。\n 技术写作中，绝大多数的句子都应该使用主动语态。本节将传授给你以下知识点：\n 如何区分被动语态和主动语态。 如何将被动语态转换为主动语态，因为主动语态通常更清晰明了。  让我们从观看一段视频开始（get the ball rolling1）：\n视频链接\n1.2.1 在简单句子中区分主被动语态 #  在主动语态的句子中，施动者施加动作于目标（actor acts on a target）。也就是说，主动语态的句子应该遵循以下公式：\n 主动语态句子 = 施动者（actor） + 谓语动词（verb）+ 目标（target）\n 被动语态句子将公司翻转。即被动语态句子通常遵循以下公式：\n 被动语态句子 = 目标（target） + 谓语动词（verb） + 施动者（actor）\n 1.2.1.1 主动语态示例 #  例如，以下是一个简短的主动语态句子：\n 猫坐在垫子上（The cat sat on the mat）。\n  施动者：猫 谓语：坐 目标：垫子  1.2.1.2 被动语态示例 #  反过来，用被动语态书写同一个句子：\n 垫子被猫坐在上面（The mat was sat on by the cat）。\n  目标：垫子 被动语态动词：被 \u0026hellip; 坐 施动者：猫   译注：在中文里被动语态的成分先后顺序与英文略有不同。可参考两个示例句子括号内的原文。\n 有些被动语态的句子忽略施动者。例如：\n 垫子被坐着（The mat was sat on）。\n 谁坐在垫子上？小猫？小狗？霸王龙（T-Rex）？读者需要自己揣测。技术文档中，好的句子会明确出：谁在对什么目标做何事。\n1.2.2 识别被动语态动词 #  被动语态动词（Passive verbs）通常遵循以下公式：\n 被动语态动词 = be 的不同形式 + 动词过去分词\n 上述公式看起来有些难，但实际上非常简单：\n be 的不同形式 通常是以下单词之一：  is/are was/were   动词过去分词通常是动词本身加上 ed 结尾。例如，下列单词都是动词过去分词：  interpreted generated formed    不幸的是，有的动词过去分词不遵循以上规律；它们不以 ed 结尾。例如：\n sat known frozen  将 be 的不同形式和动词过去分词连在一起，就是被动语态动词，比如：\n was interpreted is generated was formed is frozen  如果短语中还包括一个施动者，那被动语态动词后面通常还跟有一个介词。（这个介词常常是识别被动语态的关键。）以下示例包含了被动语态动词和介词：\n was interpreted as is generated by was formed by is frozen by  1.2.2.1 祈使动词通常都代表主动语态 #  有时很容易误将以祈使动词开头的句子认为被动语态。祈使动词是一个命令语气。很多带序号的列表以祈使动词开头。例如，下列句子中打开和设置就是祈使动词：\n 打开配置文件。 设置 Frombus 变量的值至 False。  虽然没有明确提到施动者，但以祈使动词开头的句子通常都是主动语态。这类句子暗示了一个施动者 你。\n1.2.2.2 随堂练习 #  标记以下句子为主动语态或被动语态：\n MutableInput provides read-only access. Read-only access is provided by MutableInput. Performance was measured. Python was invented by Guido van Rossum in the twentieth century. David Korn discovered the KornShell quite by accident. This information is used by the policy enforcement team. Click the Submit button. The orbit was calculated by Katherine Johnson.   译注：由于在中文里主被动语态标志较为明显，因此习题不进行翻译，有兴趣的读者可以尝试完成。\n 点击本链接查看原答案。\n1.2.3 在复杂句子中区分主被动语态 #  很多句子中有多个动词，其中有的动词是主动式，有的动词是被动式。例如，以下句子包含两个动词，且两者都是被动语态： 同一个句子，部分转为主动语态： 还是同一个句子，现在全部转为主动语态： 1.2.3.1 随堂练习 #  下列句子每个都含有两个动词。给每个动词进行分类，分为主动语态或被动语态。例如，如果第一个动词是主动语态，第二个动词是被动语态，记为 主动，被动。\n The QA team loves ice cream, but the writers prefer sorbet. Performance metrics are required by the team, though I prefer wild guesses. When software engineers attempt something new and innovative, a reward should be given.  点击本链接查看原答案。\n1.2.4 优先使用主动语态 #  绝大部分场景都要使用主动语态。尽可能少用被动语态。主动语态有以下好处：\n 大多数读者都在心中将被动语态转换为主动语态。为何还要让你的读者花费额外的处理时间呢？通过保持主动语态的使用，能让读者跳过预处理阶段，直接进行内容的编译。 被动语态模糊化你想表达的主旨，改变了原有的观点。被动语态描述行为不够直接。 有些被动语态句子完全省略了行为的施动者，迫使读者进行猜测。 通常，主动语态句子比被动语态句子更短。  请大胆使用主动语态（Be bold—be active）。\n1.2.4.1 科研报告中的语态（选读） #  被动语态在科研报告中泛滥出现。在这些研究报告中，研究者和研究设备经常消失，以如下的被动语态形式开头：\n 有人指出（It has been suggested that）\u0026hellip; 根据相关数据（Data was taken）\u0026hellip; 根据统计的数据（Statistics were calculated）\u0026hellip; 依据对结果的分析（Results were evaluated）\u0026hellip;  我们能看出来谁对何物做了什么事吗？不能。被动语态让信息更加客观吗？并没有。\n很多科学期刊已经选择拥抱主动语态。我们鼓励其他的科研内容也追求清晰明了的表达形式。\n1.2.4.2 随堂练习 #  将下列被动语态句子改写为主动语态。其中有些句子只有部分是以被动语态书写的；保证改写后所有部分都使用主动语态：\n The flags weren\u0026rsquo;t parsed by the Mungifier. A wrapper is generated by the Op registration process. Only one experiment per layer is selected by the Frombus system. Quality metrics are identified by asterisks; ampersands identify bad metrics.  点击本链接查看原答案。\n  “Getting the ball rolling” 是个惯用语，含义与 “to get something started.” 相似。 \u0026#x21a9;\u0026#xfe0e;\n   "});index.add({'id':1,'href':'/tech-writing/docs/one/clear-sentences/','title':"Clear Sentences",'section':"One",'content':"1.3 清晰易懂的句子 #   预计阅读时间：10 分钟\n 喜剧作家寻求最有趣的结果，恐怖作家力求惊悚，而技术作者追求简洁明了。在技术写作中，保证内容清晰的优先级是最高的。本节提供一些使你能把句子写得更漂亮的方法。\n1.3.1 使用强动词（Strong Verbs） #  许多技术作者都认同动词是句子中最重要的部分。选对动词，句子的剩下部分就不需要操心了。可惜，一些作者只使用一小部分平淡的动词，这就像为你的顾客提供不脆的脆饼和潮湿的生菜一样。选用正确的动词可能会花费多点时间，但是能获得更满意的结果。\n为了吸引和引导读者，使用描述精确、具体的强动词。减少不准确、宽泛的弱动词，比如：\n be 的不同形式：is，are，am，was，were 等。 occur happen  举例，思考一下如何加强下列句子中的弱动词，将它们擦亮为更吸引人的句子：\n   弱动词 强动词     错误发生（occurs）在点击提交按钮的时候。 点击提交按钮的时候触发（triggers）错误。   这条错误信息在 \u0026hellip; 时出现（happens) 当 \u0026hellip; 时系统产生（generates）这条错误信息   我们（We are）非常小心以确保（to ensure）\u0026hellip; 我们小心地确保（ensure)\u0026hellip;    很多作者依赖 be 的不同形式，仿佛这是唯一的选择。请播种不同的动词到你的写作中，让作品变得更加诱人。尽管如此，有时 be 的不同形式是最佳选择，所以也不一定要消灭所有对 be 的使用。\n注意类动词（generic verbs）可能提示着其他问题，如：\n 句子不准确或缺失施动者（actor） 句子使用了被动语态  1.3.1.1 随堂练习 #  改写下列句子，选用更具体的动词让句子更清晰。为了达成这个目标，你可以重新编排句子，增加、改动或删除词汇：\n 当变量声明缺少数据类型，会出现编译错误。 当你在声明末尾漏了分号的时候，会出现编译错误。  点击本链接查看原答案。\n1.3.2 减少 there is/there are 的使用 #  以 There is 或 There are 开头的句子将类名词（generic noun）和类动词绑在一起。这种类的词组对让读者厌烦。请用真正的主语和动词来打动你的读者。\n最佳解决方案，只需简单地去掉 There is 或 There are（可能还包括它们后面的一到两个词）。例如，以下句子：\n 有个叫 met_trick 的变量存储着当前精度。\n 移除 There is，用更好的主语代替类主语。比如下列两个句子都比原来的更清晰明了：\n 名为 met_trick 的变量存储着当前精度。 met_trick 变量存储着当前精度。\n 有时你可以通过将句子末尾真正的主语和动词移到开头，来修复一个包含 There is 或 There are 的句子。举例，可以看到代词 你 出现在句末：\n 有两个关于 Perl 的恼人事实你应该知道。\n 用 你 代替 有\u0026hellip; 可以强化句子表达：\n 你应该知道两个关于 Perl 的恼人事实。\n 在其他情况中，有的作者使用 There is 或 There are 来避免浪费功夫创造一个主语。如果句子中不包含主语，可以考虑编一个。譬如，以下的 There is 表达就不表述它想指代的实体：\n 没有任何保证（There is no guarantee that）修改可以保持顺序地被接收。\n 用一个有含义的主语代替“There is”（比如 客户端）可以得到一个体验更好的表达：\n 客户端可能不会顺序地收到修改。\n 1.3.2.1 随堂练习 #  通过移除 There is 、重新编排、修改、加减额外词汇，来简化以下句子：\n There is a lot of overlap between X and Y. There is no creator stack for the main thread. There is a low-level, TensorFlow, Python interface to load a saved model. There is a sharding function named distribute that assigns keys.   译注：为了更方便结合本节内容，习题不作翻译，有兴趣的读者可以思考完成\n 点击本链接查看原答案。\n"});index.add({'id':2,'href':'/tech-writing/docs/one/words/','title':"Words",'section':"One",'content':"1.1 遣词造句 #   预计阅读时间：10 分钟\n 我们对文档进行了大量研究，结论就是，要写出好的句子，主要看如何使用词汇。\n1.1.1 给出新词条的定义 #  写作或者编辑的时候，学会识别出哪些词条对于你的部分或全部读者来说会不熟悉。若存在这样的词条，可以采取以下两种策略：\n 如果词条已经存在，链接至一个已有的、正确的解释。（不重复造轮子。） 如果你的文档要详细介绍这个词条，那么给出它的定义。如果你的文档要介绍多个词条，把它们的定义放到一个术语表中。  1.1.2 对词条的使用要一致 #  如果你在方法中换用不同的变量名代表同一个内容，你的代码无法完成编译。类似地，如果你在文档中突然换用另一个词条名，你的想法也没办法在读者脑海中编译成功。\n规范就是：在整篇文档中都使用一致的、含义清晰的词或词条（来指代同一个事物）。你如果称了它为这东西（thingy），就不要再改称为这样物品（thingamabob）。比如，以下的示例段落错误地将 Protocol Buffers 改称为 protobufs：\n Protocol Buffers 提供了它自己的定义语言。Blah，blah，blah。这就是为什么 protobufs 能有这么大的市场。\n 如你所见，技术写作似乎很难，很多表达受限，但是它也提供了一些灵活变通的方法，即，当引入一个很长的概念术语或者产品名称的时候，你可以明确定义它的缩写。其后，你就可以在整篇文档中使用该缩写。举个例子，以下段落就没出现之前的错误：\n Protocol Buffers（以下简称 protobufs） 提供了它自己的定义语言。Blah，blah，blah。这就是为什么 protobufs 能有这么大的市场。\n 1.1.3 正确使用首字母缩写 #  在文档或小节内，首次使用某个不熟悉的缩写词时，先将完整的词拼写出来，然后将它的缩写放在括号内。将完整拼写和首字母缩写都加粗表示。示例如下：\n 该文档是面向不熟悉 Telekinetic Tactile Network（TTN）以及想要了解如何通过手部动作操纵 TTN 零件的工程师。\n 你可以在给出定义之后继续使用缩写，像以下例子一样：\n 如果没有缓存的条目存在，Mixer 调用 OttoGroup Server（OGS）从请求中获取 Ottos。OGS 是一个持有所有可供服务的 Ottos 的仓库。OGS 是以 1 个根节点和 2 层叶子节点的逻辑树的结构来组织的。OGS 的根节点转发请求至叶子节点，并收集它们的响应。\n 不要在同一个文档中来回切换着使用完整词条和首字母缩写。\n1.1.3.1 使用首字母缩写还是完整词条？ #  尽管你已经可以正确地引入和使用缩写，但是真的应该用它呢？通常首字母缩写可以缩短句子长度。比如，TTN 就比 Telekinetic Tactile Network 短两个词。但是，缩写词只是一个抽象层；读者心里需要将刚刚学到的缩写词展开成完整词条。例如，读者在脑海中将 TTN 展开成 Telekinetic Tactile Network，因此，相比起完整词条，更为简短的缩写词实际上需要更长的时间去理解和处理。\n被频繁使用的缩写词会演变出它自己的特征。在出现了一定的次数后，读者就可以不再将其展开。比如很多 Web 工程师就已经忘记 HTML 的全称。\n以下是使用首字母缩写的准则：\n 不要为仅使用寥寥几次的词定义一个缩写词。 为同时满足以下规则的词定义缩写词：  缩写词显著短于完整词条。 缩写词要在文档中出现多次。    1.1.3.2 随堂练习 #  请修改以下段落。假设这个段落是 MapReduce 在全文中首次出现之处，且 MR 是它最合适的首字母缩写。\n Jeff Dean 在 1693 年发明了 MapReduce，在由沙滩上的沙子、蜡纸、羽毛笔和烤箱为原料制造的硅基电脑上实现了它的算法。这个版本的 MR 直到 2014 年以前都一直保持着性能方面的多项世界纪录。\n （以上段落只为了幽默表达，并不属实。）\n点击本链接查看原答案。\n1.1.4 消灭有歧义的代词 #  很多代词指代前文引入的名词。这些代词就像编程中的指针。跟指针类似，代词可能会引入错误指代。不正确地使用代词会在读者脑海中产生错误的等价认知或空指针异常。在很多情况下，你应该避免使用代词，直接复述原先的名词。但是，有时使用代词的带来好处也会超过它的坏处（比如在本句中）。\n考虑以下的代词使用准则：\n 仅在引入了特定名词之后使用代词；永远不要在引入前使用代词。 将代词放在离指代对象尽可能近的位置。通常来说，如果你的名词和代词间隔超过 5 个词汇，可以考虑再重复一次名词，而非使用代词。 如果你在名词和代词之间还引入了别的名词，那就复用之前的名词，而不要使用代词。  1.1.4.1 它（It）和它们（They） #  以下的代词在技术文档中最常引起混淆：\n 它（it） 它们（they，them 和 their）  例如，在下面的句子中，它 指代的是 Python 还是 C++？\n Python 是解释型语言，而 C++ 是编译型语言。它 有着近乎狂热的追随者。\n 另一个例子，它们 指代的是什么？\n 使用 Frambus ，或搭配 HoobyScooby 使用 Carambola，或使用 BoiseFram 的时候要当心，因为 它们 核心中的 bug 可能导致意料之外的大范围好友关系解除。\n 1.1.4.2 这（This）和那（That） #  再看另外两个容易出问题的代词：\n 这（this） 那（that）  例如，下面这句模棱两可的句子，这 可以指代用户 ID 或执行处理，或同时指代两者：\n 执行处理会配置权限并生成一个用户 ID。这 让用户能被应用成功认证。\n 为了方便读者，请避免在指代不清晰的情况下使用 这 或 那。用以下的策略之一来消灭这 和 那：\n 将 这 或 那 替换成恰当的名词。 将一个名词紧贴 这 或 那 之后放置。  如下示范对第二个例句进行重写，必要时替换或者添加明确的词条：\n 这个用户 ID 让用户得以被成功认证。 配置权限的过程让用户得以被成功认证。 权限和用户 ID 两者让用户得以被成功认证。\n 1.1.4.3 随堂练习 #  辨别出以下段落中，模棱两可的代词所有可能的指代对象：\n Aparna 和 Phil 与 Maysam 和 Karan 共同分担责任，他们将轮候下次 on call。 你可以通过配置文件或在运行时动态地引入 Carambola 数据。这可能是个安全隐患。  点击本链接查看原答案。\n"});index.add({'id':3,'href':'/tech-writing/docs/overview/','title':"Overview",'section':"Docs",'content':"课程总览 #  以下表格归纳了技术写作课程的内容：\n   Title Summary Pre-Class In-Class     Chapter 1: 技术文档 了解技术写作的关键基础。进入其他课程之前先学习这一课。 2 小时 2 - 2.5 小时   Chapter 2: 技术沟通技巧 技术写作中4个中级目标的实践。 1 小时 2 - 2.5 小时    课前部分介绍了不同的学习目标；课内部分帮助读者深入和进行实践。也就是说，课前部分本身即具有一定的学习价值。\nGoogle 提供了在公司或组织进行课内学习需要的所有材料。若希望在了解如何在公司或组织进行课程指导，请查看指导技术写作课程。\n 备注：Google 偶尔会对公众提供免费的课内学习场次。详见公告。\n 技术写作课程 Chapter 1 与 Chapter 2 的目标读者为：\n 软件工程师 软件工程或计算机科学的学生  另外，许多与软件工程师打交道（如产品经理）的读者也可以从这些课程中受益。\n"});})();