2024年技术文档写作基础-写作新手必看，字节大神强推千页PDF学习笔记

最新推荐文章于 2024-09-08 16:27:09 发布

2401_84926700

最新推荐文章于 2024-09-08 16:27:09 发布

阅读量760

点赞数 22

文章标签： go 学习面试

本文链接：https://blog.csdn.net/2401_84926700/article/details/138880629

版权

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，涵盖了95%以上Go语言开发知识点，真正体系化！

由于文件比较多，这里只是将部分目录截图出来，全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频，并且后续会持续更新

如果你需要这些资料，可以戳这里获取

点击这里获取Word版本，带格式

1 搞清楚主谓宾

文档主要由段落组成，段落由句子组成，而大部分句子又由“主谓宾”组成（可能有些场合省略了，但是读者可以通过上下文轻松get到）。主谓宾是主干骨架，其他内容可以看作是句子的修饰，主干骨架是决定句子是否垮掉的主要原因。现在很多人可能已经忘记了句子的基本构成，毕竟以汉语为母语的人，大概率是不太会关心这些“细节”，就像说英语的国家可能不太关心am is are一样，你说哪个人家都理解。但是，文档中的一句话读起来是否别扭，大多数时候是由句子构成决定的。在不考虑文档上下文的情况下，如果一个句子能包含正确的主语、谓语和宾语（可选），那么它读起来至少是很顺口的。下面举一个明显搞不清主谓宾的例子：

<×>
传统图像处理算法，通过计算烟火颜色特征，极易受烟火周围环境相近颜色干扰而造成误检。

尽管你能读懂作者想要表达的意思，但是这句话读起来还是太别扭。“传统图像处理算法”应该算是主语，后面的“通过…”这句不完整，“极易受…干扰”这句还可以，“…造成误检”算是谓语宾语，但是这里用错了动词，为什么是“算法造成误检”，难道不是“周围环境相近颜色干扰造成误检”吗？

这句话的主干内容是：算法极易受…影响而…。正确的表述应该类似下面这样：

<√>
因为传统图像处理算法通过计算烟火颜色特征去识别烟火，所以它极易受烟火周围环境相近颜色干扰而出现误检。

我们用过渡词（因为…所以…）将原来的句子拆成了前后两个部分，前面部分的主语是“传统图像处理算法”，谓宾是“识别烟火”；后半部分的主语是“它”，谓宾是“出现误检”。经过调整后，前后两个部分的主语是同一个：传统图像处理算法。下面再直观看一下修改之后的句子主干骨架：

<因为><传统图像处理算法>通过计算烟火颜色特征去<识别烟火>， <所以><它>极易受烟火周围环境相近颜色干扰而<出现误检>。

如果你觉得用“因为…所以…”不太好，那么可以再换一种表述：

<√>
传统图像处理算法通过计算烟火颜色特征去识别烟火，烟火周围环境相近颜色的干扰极易造成误检。

第一句还是跟之前一样，主语是“传统图像处理算法”，第二句主语变成了“干扰”，谓宾是“造成误检”。下面我们直观地看一下修改之后的句子主干骨架：

<传统图像处理算法>通过计算烟火颜色特征去<识别烟火>，烟火周围环境相近颜色的<干扰>极易<造成误检>。

最后再举一个错误的例子：

<×>
由于误报率与漏报率很高，因此不管是否有真实事件发生都会去留意，也会有规定的日程定点巡查视频任务。

上面这个句子的作者完全没搞懂谁是主语，谁是谓语。感兴趣的童鞋可以试着修改一下，改成你认为正确的表述。

2 不滥用代词、过渡词和标点符号

2.1 不滥用代词和过渡词

中文文档中的代词主要有：你我他她它、其、前者、后者、这样、那样、如此等等，过渡词主要有：因为/所以、不但/而且、首先/然后等等。下面这张表格列举了一些常见的代词和过渡词及其常用场合：

表2-1 代词和过渡词举例

序号类型名称常用场合举例


1	代词	其	C语言中引入了“指针”的概念，其作用是为了能够提升内存访问速度。
2	代词	后者	C语言发明于1970年代，C++语言发明于1980年代，后者主要引入了面向对象思想。
3	代词	此	指针能够提升程序访问内存的速度，但此特点仍存在一些缺陷。
4	代词	它	C语言的一大特性是指针，这就像C++语言和它的面向对象思想一样。
5	过渡词	因为/所以	因为神经网络可以自动提取数据特征，所以基于神经网络的深度学习技术中不再有传统意义上的“特征工程”这一概念。
6	过渡词	首先/然后	首先我们要保证有足够多的训练数据，然后我们再选择一个适合该问题的神经网络模型。

代词和过渡词就像标点符号一样，容易被滥用。代词滥用主要体现在作者在使用它们的时候并没有搞清楚它们代表的究竟是谁，是前一句的主语、还是前一句的宾语或者干脆是前一整句话？过渡词滥用主要体现在作者在使用它们的时候并没有搞清楚前后两句话的逻辑关系，是递进还是转折或者是因果？（过渡词滥用频率要低很多，毕竟搞清楚前后句子逻辑的难度要小）接下来举几个滥用代词和过渡词的例子：

<×>
C++语言发明于1980年代，它支持“指针”和“面向对象（Object-Oriented）”两个特性，其价值在计算机编程语言历史上数一数二。

上面这个句子中出现了两个代词“它”和“其”，抛开句子内容本身对错不论，第二个代词指向的对象其实并不明确，“其”指的是“指针”、“面向对象”还是“C++语言”？或者是指“C++语言同时支持…两个特性”这个陈述？像这种有歧义的场合，我们应该少用代词，尽量用具体的主语去代替：

<√>
C++语言发明于1980年代，它支持“指针”和“面向对象（Object-Oriented）”两个特性，C++的价值在计算机编程语言历史上数一数二。

如果你一定要用代词，那么调整一下可能更好：

<√>
C++语言发明于1980年代，它同时支持“指针”和“面向对象（Object-Oriented）”两个特性，这个价值在计算机编程语言历史上数一数二。

再读一读，你是不是没有感觉到歧义了？我们在“支持”前面增加了一个“同时”，然后将代词换成了“这个”，现在这个代词指的是“C++语言同时支持…两个特性”这个陈述，修改后整个句子的意思更明确。

我们再来看另外一个滥用代词的例子：

<×>
该模块主要负责对视频进行解码，输出单张YUV格式的图片，并对输出的图片进行压缩和裁剪，前者基于Resize方法来完成，后者基于Crop()方法完成。

对于大部分人来讲，上面这段没什么问题。代词“前者”指的是压缩、“后者”指的是裁剪，原因很简单，因为单词Resize对应的是压缩、单词Crop对应的是裁剪。但是这段话如果拿给没有任何知识背景的人去读（大概率可能是找不到这种人），恐怕会存在歧义，主要原因是代词前面提到了很多东西，“前者”和“后者”指向不明确，到底是指“解码”、“输出单张图片”还是后面的“压缩”和“裁剪”？下面这样调整后，整段话的意思更加明确：

<√>
该模块主要负责对视频进行解码，输出单张YUV格式的图片，并对输出的图片进行压缩和裁剪，压缩基于Resize方法来完成，裁剪基于Crop()方法完成。

我们去掉了代词，直接用具体的主语来代替，句子意思非常明确。如果你一定要使用代词，那么也可以这样调整：

<√>
该模块主要负责对视频进行解码，输出单张YUV格式的图片。同时，它还对输出的图片进行压缩和裁剪，前者基于Resize()方法完成，后者基于Crop()方法完成。

上面这段话还是使用了代词“前者”/“后者”，但是我们修改了标点符号，并且增加了一个过渡词“同时…”，这样做的目的是让读者知道虽然整段话说的是同一个东西，但是前后的句子已经分开了，为我们后面使用代词做好准备。

好的，现在我们来总结一下在技术型文档编写过程中使用代词时的一些有价值经验：

代词可以指它前面出现过的名词、短语甚至整个句子，但是一定是前面出现过的；
代词的位置和它要指向的目标最好不要隔得太远，1~3句话之内，超过就不要用了；
代词的作用是减少小范围内某些词汇或句子重复出现的频率，要用到恰到好处；
代词前面出现的混淆目标如果太多，一定要重新调整句子，确保代词指向无歧义。

2.2 不滥用标点符号

接下来我们再看另一个，标点符号的滥用要普遍很多，其主要原因是：标点符号的使用并没有非常明确的对错之分。至少对大部分人而言，使用句号还是逗号其实并没有什么严格的评判标准，只要不出现“一逗到底”的极端情况，其余大概率都OK。下面这张表格是我根据以往经验，总结出来的应用于技术型写作时中文标点符号使用规则：

表2-2 常用标点符号

序号符号写法使用场合


1	逗号	，	前后两句话关联性比较大，阅读时停顿时间短。
2	句号	。	前后两句话关联性比较小，阅读时停顿时间稍长。
3	分号	；	前后两句话地位相对平等，句子的内容和格式基本保持一致。比如列表中，如果每项是一个句子或者短语，那么第1至第N-1项结尾使用分号，第N项结尾使用句号。
4	冒号	：	技术型文档中，冒号一般用在需要引入重要内容的场合。比如当你需要插入一张表格或者一张图片时，需要提前做一个提醒（下表列举了常见的代词和过渡词：），提醒结束时补充一个冒号。
5	括号	（）【】	（）一般用于解释性的场合，负责对名词或者句子的补充解释。【】用得比较少，我一般用于需要增加醒目标记的名词或短语中。
6	顿号	、	一般可以用在枚举名词或者短语的场合。
7	问号	？	不用多解释。
8	引号	“” ‘’	一般用于标记特殊名词、专用名词、短语，或需要重点突出的名词或短语。
9	分隔号	/	一般用于成对出现的名词（举例：因为/所以、首先/然后等等都是过渡词），或者根据文档上下文来判断地位差不多的相近词（举例：算法的好坏直接影响最终报表中误报/误报率那一栏）。
10	破折号	——	用得不多。
11	省略号	…	不用多解释。
12	感叹号	！	技术型文档不是写小说，用得不多。
13	书名号	《》 <>	不用多解释。

上面这张表格基本涵盖了常用的中文标点符号，其中有一小部分在技术型文档中不太常见，比如感叹号、破折号，这些符号多多少少带有某种感情色彩，不太适合用于技术型文档编写。前面已经简单概括了一下各个符号的使用场合，下面挑几个容易出错的再一一详细说明：

<×>
C++语言发明于1980年代，它衍生自C语言，主要引入了“面向对象（Object-Oriented）”思想，面向对象思想强调对数据的封装和对功能的复用，此特性有利于开发者对代码的维护和扩展，目前，大部分计算机编程语言已经支持了面向对象特性。

上面这段话属于典型的“一逗到底”的例子。作者从C++语言说到了面向对象思想，最后总结大部分计算机编程语言都支持面向对象。我们如果将整段话拆开来看，其实它想表述的是3个内容，每个内容之间最好使用句号，停顿时间稍长一些。我们调整之后的效果是：

<√>
C++语言发明于1980年代，它衍生自C语言，主要引入了“面向对象（Object-Oriented）”思想。面向对象思想强调对数据的封装和对功能的复用，此特性有利于开发者对代码的维护和扩展。目前，大部分计算机编程语言已经支持了面向对象特性。

接下来我们再看看分号的使用。根据我个人经验，分号常用在列表场合，下面举一个例子说明：

下面是“将大象装入冰箱”的具体步骤：

打开冰箱门；
将大象装进冰箱；
关上冰箱门。

上面是一个有序列表，列表中的各项内容是一个短语。当列表中各项内容是短语或者句子的时候，除最后一项之外其余项目结尾一般都使用分号（注意，同一个列表中各项的格式最好都保持一致，要么都是短语，要么都是单个的名词，这个后面专门讲列表的时候会提到）。如果列表中各项内容只是一个名词时，那么结尾就可以不用标点符号：

下面是“可以被装进冰箱”的动物：

狗子
大象
猴子
鹦鹉

上面是一个无序列表，列表中的各项内容是一个名词，这时候名词结尾处不需要添加任何标点符号。

我们最后再来看一下小括号的使用场合。在技术型文档中，小括号主要用于对前面的名词、短语或者句子进行补充说明，比如当文档中出现缩写词汇时，我们会在它的后面增加一个小括号，在括号里面注明该缩写词汇的全称。下面举一个使用小括号对缩写词汇解释说明的例子：

API（Application Program Interface）是系统对外提供的访问接口，使用者可以按照API文档中的接口定义去访问系统中的数据，并与它做一些交互。

上面这段话主要讲API是什么、可以干什么。它是Application Program Interface三个单词的简称，为了让读者更清楚该术语的定义，作者可以选择在第一个“API”出现的位置增加一个小括号，并将术语全称补充进来，之后的整个文档无需再重复该操作（后面会单独提到术语全称和简称的运用规则）。

除了能对缩写词汇进行解释说明之外，小括号还可以用于对前面整个句子进行补充说明，再看下面这个例子：

它是Application Program Interface三个单词的简称，为了让读者更清楚该术语的定义，作者可以选择在第一个“API”出现的位置增加一个小括号，并将术语全称补充进来，之后的整个文档无需再重复该操作（后面会单独提到术语全称和简称的运用规则）。

上面这段话其实前面已经出现过，最后小括号里面的内容主要是为了对它前面一句话进行补充。如果补充性说明内容太长，比如要好几句话才能起到补充的作用，那么这个时候我们就不应该再使用小括号了，可以考虑调整句子结构，然后将补充性的内容当作段落主体的一部分。

关于代词、过渡词以及标点符号滥用的内容就讲到这里，其中有一些内容是我个人的写作喜好，其实并没有非常明确的对错之分，比如前面讲到列表中分号的使用，很多人这时候可能选择使用句号。大家可以根据自己的判断去处理这种模棱两可的场景，当然一些比较确定的规则，比如当列表项只有名词的时候，列表项结尾不要使用任何标点符号，这一点还是比较确定的。

3 多用强势动词，少用形容词和副词

3.1 强势动词和主动语句

很多人可能第一次听到“强势动词”这个说法，陌生还难以理解。如果将它翻译成英文，对应的单词应该是“Strong Verbs”，意思是强有力的动词，你可以理解为：听起来动作幅度大、冲击力强的那一类动词。打个比方，假如“走”是弱势动词，那么“跳”就是强势动词；假如拿刀“切”是弱势动词，那么拿刀“砍”就是强势动词。下面这张表格列举了一些强势/弱势动词的例子：

表3-1 强势/弱势动词对比

序号弱势动词（可考虑）强势动词


1	走过去	跳过去
2	切肉	砍肉
3	出现异常	抛出异常
4	程序退出	程序崩溃
5	内存增长	内存泄漏
6	找不到日志文件	日志文件丢失
7	客户提出质疑	客户投诉
8	任务未完成	任务延期
9	角色权限是由管理员设置的	管理员控制角色权限
10	系统无法正常使用API返回的结果	系统无法正常解析API返回的结果

上面列出了10对强势/弱势动词，我们观察可以发现：弱势动词一般无法正确表达问题/事情的真实情况。在技术型文档编写过程中，虽然我们不能借助词汇使用、句子构成以及标点符号等手段去传递感情倾向，但是也不能掩盖真实准确的内容表达。

在提到强势动词时，我们还要注意“主动语句”和“被动语句”的区别。在技术型文档编写过程中，应该尽量少使用被动语句。下面这张表格列举了一些主动/被动语句的例子：

表3-2 主动/被动语句对比

序号被动语句（可考虑）主动语句


1	角色权限是由管理员控制的	管理员控制角色权限
2	API结果无法被系统正常解析	系统无法正常解析API结果
3	图像特征是通过CNN逐步降维的方式提取的	CNN通过逐步降维的方式提取图像特征
4	这种检测效果无法被客户接受	客户无法接受这种检测效果
5	经过研发排查发现，这个现象是正常的（*）	经过研发排查发现，这个属于正常现象

上面表中第5项（带*号）严格来讲不算被动语句，但是在技术型写作过程中，我们应该避免使用“…是…的。”这种句式，该句式太过口语化。尽量少用被动语句的原因有以下三个：

读起来麻烦。读者读到被动语句时，需要先在脑子里将其转换一下再去理解；
难以理解。读者有时候很难分清被动语句中的真实主语（甚至可能省略了主语）；
字数多。被动语句一般更长、字数更多。

那么被动语句是不是完全不让用了呢？当然不是。仔细的读者可能已经观察到了前面在举例的时候我们有这样一段话：

C++语言**<发明于>**1980年代，它支持“指针”和“面向对象（Object-Oriented）”两个特性，C++的价值在计算机编程语言历史上数一数二。

上面第一句中的“…于”其实就是被动语句，像“C++语言发明于…”、“该文档编辑于…”这些都算被动语句，由于宾语（这里是C++语言）更重要，所以默认省略了真实主语（某某发明C++语言，可是某某在这里不太重要）。这类句子结构有一个特点就是：宾语比真实主语重要，所以放到句子的开头位置。

3.2 少用形容词和副词

技术型文档讲究的是一个“准”字，它不像小说、散文之类的文学作品带有很强的感情色彩，也不同于网络博客可以掺杂一些非正式词汇，更不能跟Marketing Speech（营销话语）一样常常夸大其词。为了做好前面说的“准”，技术型文档应该尽量少用形容词和副词，因为这些词语大部分都属于“主观”表达。下面举几个使用形容词和副词的例子：

<×>
为了保证系统运行更高效，他们尝试尽可能压缩图片尺寸，事实证明这个尝试非常成功。这样的工作看似简单，却蕴含着高技术含量。

上面这段话使用了好几个副词和形容词，比如“尽可能”、“非常”、“高”。如果是技术型文档，这段话建议调整为：

<√>
为了提高系统运行效率，他们将图片尺寸压缩到原来的1/3，系统响应速度提升2倍。

我们用具体的数值替换了原来的形容词和副词，并且直接删掉了最后一句话，最后一句话在技术型文档中起不到任何作用。下面这张表格列举了部分形容词和副词使用不恰当的场合：

表3-3 形容词/副词使用不恰当举例

序号形容词/副词（可考虑）调整为


1	经过优化，接口响应速度提升明显	经过优化，接口响应速度提升2倍
2	很多人反应现场误报很多	数据统计发现，现场误报率为11%
3	大部分客户投诉说系统很不好用	最近一个月有超过50个客户投诉说系统不好用
4	升级依赖库后，该函数运行很快	将依赖库升级到2.3.1版本后，该函数执行时间缩短到100ms以内
5	研发同事很辛苦，每天加班很晚	研发同事很辛苦，每天23:00之后才下班

最后，我们来总结一下：

优先使用方便读者阅读理解的动词和句式（强势动词和主动语句）；
尽量少用形容词和副词，用具体数值代替、或者调整句子表述。

4 正确使用术语

这里提到的术语分两种：一种是计算机领域通用的专业术语，像SDK、面向对象、TCP/IP、微服务等等这些名词，它们基本已经被大众接受和理解，我们在编写文档的时候不能随意再重新去命名、调整或者改变拼写（将“TCP/IP”写成“Tcp/ip”）；另外一种是当前文档需要定义的术语，这种术语只有在当前文档上下文中才有效。我们在编写技术型文档时，通过自己的判断，如果认为文档读者缺乏对相关术语（不管是前面哪一种）的理解，我们都应该在文档靠前位置给出对术语的解释说明，也就是我们平时文档中常见的“名词解释”。

表4-1 名词解释举例（*为自定义术语）

序号名词说明


1	SDK	Software Development Kit，软件开发包，开发者基于该工具包开发更丰富的高层应用。
2	内存泄漏	通过new/malloc等方法申请的内存在使用完后未被及时释放，程序运行内存占用越来越高。
3	面向对象	强调对数据和功能的封装，提升代码的可复用性、可扩展性以及灵活性。
4	FVM（*）	Front Video Manager，前端视频管理服务，负责视频接入、分发等业务。
5	视频大数据标签服务（*）	对视频进行结构化处理，生成结构化标签，并对外提供标签检索等功能。

有些文档可能篇幅比较短，并不是传统意义上的需求设计类文档，比如对某个线上问题分析的结果汇报、对某个模型检测效果的验证报告、或者研发阶段性的工作总结。这些文档由于本身内容就不多，大部分可能直接进入主题，这时候如果还要在文档中专门增加一块名词解释的版块（并且总共也就一两个术语），就显得比较突兀。

另外一种对术语进行解释说明的方式是用我们前面提到的小括号，我们可以在术语后面增加一个小括号，然后在括号里添加补充说明。这种方式很便捷，但是只适合简单的场景，比如在小括号里面补充术语的全称或者简称，或者只做简单的解释说明。如果对一个术语的解释内容很长，就不太适合用这个方法，下面举一个错误的例子：

<×>
当视频离线时，FVM（Front Video Manager，前端视频管理服务，负责视频接入、分发等业务。）会产生一条告警记录，并存入节点数据库。

上面这个术语解释内容太长，不太适合使用小括号的方式，这种情况要么在文档正文中专门对FVM进行解释，要么在小括号中只给出FVM的英文全称即可：

<√>
当视频离线时，FVM（Front Video Manager）会产生一条告警记录，并存入节点数据库。

使用小括号去做术语解释还需要注意一点的是：只需要在术语第一次出现的时候做一次解释即可，不需要重复多次。下面举一个重复的错误例子：

<×>
当视频离线时，FVM（Front Video Manager）会产生一条告警记录，并存入节点数据库。之后节点数据库会将该条告警记录同步到平台数据库，平台FVM（Front Video Manager）检测到有新的告警记录时，会通过消息中间件通知业务系统，业务系统随后将告警信息以短信（或钉钉）的方式通知到用户。

上面对术语FVM的解释重复了两次，这种做法是错误的，第二次我们可以直接去掉。

有些术语存在全称和简称，我们熟悉的SDK全称是“Software Development Kit”，但是现在基本没有人再去使用它的全称。像这种简称已经被大众熟知的术语，我们就不能再标新立异的去用它的全称。另外一些在文档中自定义的术语，文档作者为了便于阅读可能也会提供一个简写的版本，在这种情况下，文档前后应该保持一致，即：要么整篇文档都用全称，要么都用简称，尽量做到一致。下面举一个全称简称使用不一致的例子：

<×>
IVA（Intelligent Video Analytics，智能视频分析）服务主要负责视频解码、模型推理、目标跟踪以及目标行为分析，该服务是整个系统中最复杂的一个模块。智能视频分析服务由张三团队开发完成，一共耗时6个月，人力成本开销120万。

上面这段话中，前半部分作者使用“IVA”简称（小括号中做了全称说明），但是在后面一句话中作者又使用了全称“智能视频分析”，这种做法没有遵循统一原则。不仅同一段落应该保持统一，整篇文档也应该做到统一，术语在文档中第一次出现时是简称，那么整篇文档都应该用简称，反之亦然。

最后我们来总结一下，在技术型文档中使用术语时需要注意的一些事项：

文档读者不熟悉的术语（包括通用术语和文档自定义术语）都应该有解释说明；
小括号只适合简短的术语解释场合，括号里的内容不能太长（一两句短语之内）；
任何方式的术语解释只需要有一次即可（术语第一次出现时），不要解释多次；
术语的全称和简称要保持使用一致，要么整篇文档都用全称、要么都用简称；
对于计算机领域的通用专业术语，需要沿用主流用法，不要随意再去调整。

5 正确使用段落

5.1 单一职责

与面向对象编程中“类的单一职责原则”一样，文档中的句子（特指以句号结尾的一句话）、段落也应该遵循“单一职责原则”。前面讲标点符号的时候已经提到过，同一段话中前后关联性不大的两句话之间用句号，这样可以保证每句话想要表达的是相对独立的内容。段落也一样，一个段落只陈述一个主题，可以保证段落的句子不会太多、内容不会太长，便于读者阅读和理解。下面举一个段落使用错误的例子：

<×>
Excel提供一个组织数据的高效方法。我们可以将Excel想象成一个有行和列的二维表格，每一行代表一个独立的实体，每一列代表该实体的不同属性。Excel还具备数学功能，比如计算平均值和方差等数学操作。如果你想使用Excel来记录图书信息，那么每一行代表不同的书本，每一列代表书本的属性，比如书的名称、价格以及出版社等等信息。

上面这段话的第一句已经明确了段落主题：Excel能高效地组织数据。可是，这段话中间却穿插了一个不相干的句子，说Excel具备数学功能，能够做一些数学操作，这句话显然跟本段主题不一致，我们需要将其去掉：

<√>
Excel提供一个组织数据的高效方法。我们可以将Excel想象成一个有行和列的二维表格，每一行代表一个独立的实体，每一列代表该实体的不同属性。如果你想使用Excel来记录图书信息，那么每一行代表不同的书本，每一列代表书本的属性，比如书的名称、价格以及出版社等等信息。

5.2 好的开头语

除了要保证段落的“单一职责”之外，我们还需要给每个段落一句“好的”开头语。那么什么是好的开头语呢？好的开头语要能让读者读完之后就能猜到文档作者在本段中想要陈述的主题，其实就是概括性的句子。还是以上面那段话为例子，它的第一句话“Excel提供一个组织数据的高效方法”其实就是很好的开头语，它提示本段内容主要讲Excel如何高效地组织数据。如果我们将上面那段话的开头调整一下，那么效果明显就差了很多：

<×>
Excel由许许多多的单元格组成，每个单元格可以包含不同的内容。我们可以将Excel想象成一个有行和列的二维表格，每一行代表一个独立的实体，每一列代表该实体的不同属性。如果你想使用Excel来记录图书信息，那么每一行代表不同的书本，每一列代表书本的属性，比如书的名称、价格以及出版社等等信息。

读者读完上面第一句话后，可能还是很懵，需要读完整段话才能明白文档作者在本段中想要表达的意思。段落的开头语可以通过提炼段落内容得到，我们可以在段落写完之后回过头提炼一句话作为本段的开头语，下面这段话描述代码中循环语句的作用：

<×>
目前几乎所有的计算机编程语言都支持循环语句，例如，我们可以编写代码来判断一个用户命令行输入是否等于“quit”（退出命令），如果需要判断100万次，那就创建一个循环，让判断逻辑代码运行100万次。

上面的这段话本身没什么问题，主要介绍循环语句的功能和应用场合。但是如果我们提炼一下，在段落开头增加一个更好的开头语，效果可能会提升很多：

<√>
循环语句会多次运行同一个代码块，直到不再满足循环条件为止。目前几乎所有的计算机编程语言都支持循环语句，例如，我们可以编写代码来判断一个用户命令行输入是否等于“quit”（退出命令），如果需要判断100万次，那就创建一个循环，让判断逻辑代码运行100万次。

上面开头第一句话就说清楚了循环结构的特点，读者读完第一句话基本就知道整段内容要讲什么。一个好的开头语能够节省读者的时间，因为并不是每个读者都有兴趣去阅读整段的内容，开头语可以给读者“是否继续读下去”一个参考。

5.3 控制段落长度

控制段落长度并没有一个明确的标准，它只是一个非常主观的说法。如果文档中某个段落内容太长（比如那种一段话就占半页Word），作者自己应该反复阅读几次再对段落做一些精简，这样既可以节省读者的时间，大概率也能提升意思表达的准确性。同样，也不太建议文档频繁出现小段落，比如整段内容只有一两句话那种，这个时候可以考虑段落合并或者稍微扩充一下内容。

最后我们来总结一下，在技术型文档中如何正确使用段落：

一个段落只负责讲一个内容，两个不同的主题应该拆分成两个段落去陈述；
尽量为每个段落增加一个“好的”开头语，能够清晰表达（或暗示）本段的主题；
要控制好段落内容长短，“不长不短”根据自己经验（比如不超5~7个句子）。

6 适当使用列表和表格

文字相对来讲其实是一种效率比较低的表达方式。如果你想让人快速地去理解你要表达的意思，图片应该是最好的一种方式，但是图片有一个缺点就是：有时候它只能从宏观上去表达，无法体现其中细节。当我们想要尽可能直观地去陈述内容，又想尽可能多的包含细节时，我们可以考虑使用列表或者表格。有些读者非常抵触大段大段的文字（尤其在技术型文档中），一种改进方法是前面提到的“控制段落长度”，尽量让段落内容精简、单一；再一个就是看看段落内容是否能以列表或者表格的方式去呈现，这种方式可以给人“严谨、清晰”的感觉。

6.1 使用列表

列表简单来讲就是将你原来用段落方式呈现的内容改用项目（Item）的方式去呈现，一般它主要用于枚举、过程描述或者要点归纳等场合。列表中的各项可以是名词、短语，甚至是句子，各项目之间有严格顺序要求的列表叫“有序列表”，相反并没有严格顺序要求的列表叫“无序列表”。下面是以段落的方式陈述小张今天所做的事情：

白天在公司上班期间，小张一共修复了7个bug，做了3个代码合并（评审），并和项目经理讨论了前天提的新需求。晚上回到家后，小张先做饭，然后给儿子洗澡，23:30上床睡觉。

上面这段话本身没什么问题，用了合理的标点符号和过渡词，读起来清晰明了。但是，如果在技术型文档编写中，能将这段话改用列表的方式呈现，起到的效果会更好：

小张白天在公司：

修复了7个bug；
做了3个代码合并（评审）；
和项目经理讨论前天提的新需求。

晚上回到家后：

做晚饭；
给儿子洗澡；
23:30上床睡觉。

我们将原来的一段话拆成了两个列表，并在每个列表前面做了一个“引入说明”（以冒号结束），介绍了接下来列表的背景上下文。第一个列表是无序列表，因为原文并没有突出强调小张白天在公司每项工作之间的前后关系（无顺序要求），只是一个归纳统计；第二个列表是一个有序列表，原文很明显强调了小张晚上回家之后做事的先后顺序（最后一项还给出了具体时间）。在技术型文档中，合理地运用列表这种方式去呈现内容可以给人一种“逻辑严谨、思路清晰”的感觉，让读者更相信你讲的内容。

在使用列表时，我们应该确保列表中各项内容结构一致，即：要么都是名词，要么都是短语，要么都是句子。这个原则既能保证你使用列表的初衷（逻辑严谨、思路清晰），也能让读者读起来更舒服。下面是一个错误使用列表的示范：