技术写作 第一课

Posted 2021-09-13 LRF成长记

本文是学习Google技术写作课程[1]的学习笔记，它这个课程主要用于指导我们如何做好技术写作，了解如何计划和编写技术文档；

本课程是技术写作中的第一课，主要学习技术写作的关键基础，在学校任何其他课程之前，请先学习本课程。

学习目标

首先我们确定学习的目标，知道学习完本课程之后可以得到什么；本课程教我们技术协作的基础，完成本课程后，我们就知道如何执行如下的操作了。

•始终使用专业术语（包括缩写词和首字母缩写词）；比如K8s中的最小调度单元Pod。•识别并尽量减少使用代词的句子。•区分主动语句和被动语句。•确定主动语句优于被动语句的三种方式。•制定至少三种形式，使句子更清晰，更加引人入胜。•制定至少四种缩短句子的策略。•了解项目符号列表和编号列表之间的区别。•创建有用的列表。•为段落创建有效的主要句子。•将每个段落集中在一个主题上。•在每个文档的开头说明要点。•确定你的目标受众。•确定你的目标受众已知什么以及需要学习什么。•了解知识的灾难。•识别和修订成语。•说明文档的范围目标和受众。•将较长的主题分为适当的部分。•真正确使用标点符号，包括括号、冒号、破折号和分号。•在Markdown中发展初学者的能力。

成为一名优秀的工程师和一名出色的技术作家，需要花费多年的专注实践，本课程将提高我们的技术写作水平，但不会使我们变成一名出色的技术作家。

足够的语法

这里主要是介绍与本课程相关的词性。

词性	定义	例子
名词	人，地方，概念或事物	山姆跑比赛。
代词	替换另一个名词（或更大结构）的名词	山姆参加比赛。他喜欢竞争。
形容词	修饰名词的单词或短语	山姆穿蓝色的鞋子。
动词	一个动作词或短语	山姆跑比赛。
副词	修饰动词，形容词或其他副词的单词或短语	山姆运行缓慢。
介词	指定两个名词的位置关系的单词或短语	山姆的运动鞋很少在他的架子上。
连词	连接两个名词或短语的单词	山姆的奖杯和缎带只存在于他的想象中。
过渡	连接两个句子的单词或短语	山姆每周参加比赛。但是，他弱势地完成了比赛。

名词

名次代表人、地方或事务。朱迪、南极洲和锤子都是名词，无形的概念（例如健壮性 和完美性）也是名词。

在框架中，对象必须复制该对象要更改的所有基础值。该PROTOS的代码库是巨大的，所以复制的PROTOS是不可接受的昂贵。

在编程中，我们会把类和变量视为名词。

练习

找出下面段落中识别六个名词

C使程序员能够控制指针和内存。强大的功能带来巨大的责任。

答案

C、指针、内存、程序员、功能、责任。

代词

代词是一个间接层，它指向或替代了其他名词或句子。例如，考虑以下两个句子：

珍妮特（Janet）编写了出色的代码。她是高级工程师。

在前面的示例中，第一句话将Janet建立为名词。第二句话用代词她代替名词珍妮特。

练习

在以下段落中确定三个代词：

自助餐厅的特色是在吐司上撒上腰果、黄油和果酱。员工们发现它很棒，希望他们每天都能吃它。

答案

它很棒: 它代指前面描述的在吐司上撒上腰果、黄油和果酱的食物。

他们每天吃：他们指代前面的员工。

吃它：它代指前面描述的食物

动词

动词是一个动作词或短语。当您要表示两个名词（一个演员和一个目标）之间的关系时，该动词会起作用。动词标识演员对目标的作用。

每个句子必须至少包含一个动词。例如，以下每个句子包含一个动词：

•酒井更喜欢意大利面。•里克喜欢大海。•蓝精灵是蓝色的。•杰西患有过敏症。

练习

在下面句子中找到动词：

萨曼莎（Samantha）正在用C ++编写“斗牛行动”。该项目目前消耗超过80,000行代码。她以前使用过Python，但最近开始使用C ++。萨曼莎（Samantha）领导着一个由四名软件工程师组成的团队，该团队将在下个季度增长到六名软件工程师

答案

编写、消耗、领导、增长

形容词和副词

形容词修饰名词。

•汤姆喜欢红气球。他准备美味的食物。他修复了 八个错误。

副词修饰动词。

•Jane可以有效地修复错误。

练习

在以下段落中确定四个形容词。

对于有才华的人来说，工程是一个伟大的事业。我认识一位聪明的工程师，可以在任何知识性的工作中脱颖而出。

答案

才华、聪明、知识性、伟大

连词和过渡

连词连接短语或名词中的句子，过渡将句子本身连起来。

最重要的连接词如下：

•和•但•或者

技术写作中最重要的过渡词如下：

•然而•所以•例如

练习

通常，Barbara在编写第一行代码之前会研究问题很长时间。\\_\\_\\_\\_\\_，前几天她突然受到启发时，自发地编码了一种方法。

答案

然而

单词

定义新术语

在编写时，识别目标受众可能不熟悉的术语，当识别出来之后，需要采取下面两种措施：

•如果该术语已经存在，请链接到现有的良好说明。（不要重新发明轮子。）•如果是新引入的术语，需要定义它，如果引入多个术语，请定义收集到词汇表中。

始终使用术语

在同一个文档中使用相同的术语，否则会让看的人疑惑。

正确使用首字母缩写

在正文中首次使用首字母缩写时，请拼写完整的术语，然后将首字母缩写词放在括号中，首字母缩写词用黑体字体标出。然后就可以在后续使用同名的首字母缩写词了。

歧义代词

许多代词都是指代前文中的名词，这种代词像编程中的指针，往往容易引入错误；在文中，尽量避免使用代词，只需要重用名词即可。可以在如下的几种情况中使用代词。

•引入名词后使用代词；在介绍名词之前，请勿使用代词。•代词应尽可能靠近指代名词，通常，如果名词和代词的距离超过五个单词，就请考虑重用名词。•如果在名词和代词之间引入第二名词，请重用名词，而不要使用代词。

它和他们

这两个代词在技术文档中引起最大的混乱：

•它It•他们they、them、their

下面句子中的它就是一个不确定的代词。

Python是解释形语言，而C ++是编译形语言，。它具有很多追随者。

这个和那个

•这This•那That

下面句子中的这就不清楚代指Frambus还是Foo。

您可以使用Frambus或Foo来计算导数。这不是最佳的。

主动语态

优先使用主动语态而不是被动语态：

清晰的句子

在技术写作中，文章写的清晰明了要优于其它规则；下面提供了几种可以使文章清晰明了的方法。

选择有效的动词

大多数技术作家都认为动词是句子中最重要的部分，选择正确的使用动词更会产生令人满意的结果。

要吸引和让读者学习，请选择精确、有力，特定的动词。减少使用不精确、通用的动词，如：

•be动词：is，are，am，was，are等。•发生

简短的句子

出于一大原因，我们会在写技术文档时把句子写的足够简短：

•简短的句子阅读起来更快。•简短的句子通常更容易维护。•较长的句子会让自己更难理解。

我们可以通过如下几点来把长句子变为短句：

•每个句子都只表达一个想法。•将一些长句子转换为列表。

原句

如：要更改循环的常规流程，可以使用break语句（使您跳出当前循环）或continue语句（跳过当前循环的当前迭代的其余部分）。

修改如下

要更改循环的通常流程，请调用以下语句之一：

•break，使您跳出当前循环。•continue，跳过当前循环的当前迭代的其余部分。

•

减少使用重复的单词

•

减少从属子句。

列表和表格

好的列表可以把混乱的技术内容转变为有序的事物，技术读者通常喜欢列表。

选择正确的列表类型

下面的列表在技术写作中经常被使用：

•项目列表。

如：Bash提供以下字符串操作机制：

•从字符串开头删除子字符串•将整个文件读入一个字符串变量

•数字编号列表。

如：请执行以下步骤来重新配置服务器：

1.停止服务器。2.编辑配置文件。3.重新启动服务器。

•潜入编号清单。

项目列表和编号列表的区别，使用项目列表的时候，重新排列项目列表中的内容，则列表的含义不会改变；使用编号列表时，重新排列编号列表中的内容，则列表的含义会改变。

保持列表项一致

列表项一致是指列表中描述每一项都使用一样的词性、标点、句子结构（如都是主动句）。

如下面句子就是列表项一致的：

•萝卜•土豆•卷心菜

下面的句子就是列表项不一致的：

•萝卜•土豆•夏日的阳光遮掩了冬天的所有回忆。

创建有用的表

大家对于表的展示信息会更加的关注。

使用表时，请注意以下几点：

•每一列的标题都要取得有意义，不要让读者去猜测。•每个单元格中不要放入过多的内容，如果超过两行，就需要仔细想一下是否需要。•争取每个列之间是相关性的。

使用表和列表前

在使用表和列表前加上一句话，告诉读者表格或者列表是要说明什么，然后用冒号来终止介绍语句。

段落

写作的工作：弄清主题各部分之间的依赖关系，并按逻辑的顺序呈现出来，使读者能够理解。

写一个好的开头

开头句子是段落中最重要的部分，好的开头确定了段落的中心思想。

每一段都只写一个主题

一段应只写一个主题，将每个段落都只写一个主题，不要描述之前的话题或者是之后的话题。

段落不要太长也不要太短

段落太长让看的人第一映像是恐惧，读者更喜欢包含三到五个句子的段落，但会避免包含超过七个句子的段落。

一个段落要提供什么

好的段落可以回答三个问题：

•你想告诉读者什么东西？•读者为什么知道这点很重要？•读者应该如何使用这些知识。

受众

如何定义受众

我们通过简单的方式来确定受众；首先确定受众的角色，示例角色包括：

•软件工程师•技术非工程师角色•科学家们•科学领域的专业人才•本科生•研究生•非技术职位

确定受众需要学习内容

在写文章之前最好能确定受众需要掌握什么知识才能更好的读懂本文，可以把受众需要掌握的以列表的形式列出来。

文档

需要把所有的段落组织成一个连贯的文档。

声明文档范围

一个好的文档应该要说明它要说明的主题，以及不会说明什么；如下：

本文档描述了Project Frambus的总体设计；本文档没有介绍相关技术Froobus项目的设计。

说明文档的范围不仅能使读者受益，也能让作者受益。在编写时，可以时刻参考自己定义的文档范围并修正。

Markdown

 Markdown是一种轻量级的标记语言，许多技术专业人员都是用它来创建和编辑技术文档，使用Markdown，通过插入特殊符号用来标示标题、粗体、列表等。

References

[1] Google技术写作课程: _https://developers.google.com...