最全技术文档写作基础-写作新手必看，【2024Golang最新学习路线

网上学习资料一大堆，但如果学到的知识不成体系，遇到问题时只是浅尝辄止，不再深入研究，那么很难做到真正的技术提升。

需要这份系统化的资料的朋友，可以添加戳这里获取

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！

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

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

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

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

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

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

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

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

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）”思想。面向对象思想强调对数据的封装和对功能的复用，此特性有利于开发者对代码的维护和扩展。目前，大部分计算机编程语言已经支持了面向对象特性。

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

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

1. 打开冰箱门；
2. 将大象装进冰箱；
3. 关上冰箱门。

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

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

• 狗子
• 大象
• 猴子
• 鹦鹉

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

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

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

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

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

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之后才下班

最后，我们来总结一下：

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

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

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

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

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），作者自己应该反复阅读几次再对段落做一些精简，这样既可以节省读者的时间，大概率也能提升意思表达的准确性。同样，也不太建议文档频繁出现小段落，比如整段内容只有一两句话那种，这个时候可以考虑段落合并或者稍微扩充一下内容。

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

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

6 适当使用列表和表格

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

6.1 使用列表

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

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

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

小张白天在公司：

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

晚上回到家后：

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

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

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

<×>
影响系统检测准确性的因素有：

• 模型；
• 产品开通过程中，工程师对算法参数校准程度；
• 应用现场是否有灯光照明。

上面列表一共包含3项，每项的内容结构各不相同，第一项是一个名词，第二项是一个句子，第三项是一个短语。我们将结构统一后，可以调整为下面这样：

<√>
影响系统检测准确性的因素有：

• 模型的复杂性；
• 部署时对算法参数校准的程度；
• 应用现场是否有灯光照明。

上面是将列表中各项内容修改为短语，我们还可以换另外一种方式：

<√>
影响系统检测准确性的因素有：

• 模型类型
• 校准程度
• 环境亮度

上面是将列表中各项内容修改为名词，由于是名词，每项结尾处不使用任何标点符号（参见前面专门讲标点符号的章节）。下面是对列表运用的总结：

1. 列表一般用于枚举、过程描述、要点归纳等场合；
2. 需要强调顺序的时候应该使用有序列表，其余视情况而定；
3. 列表中各项内容结构应保持一致，都是名词、短语或者句子；
4. 每个列表前面尽量添加一个明确的“引入说明”，以冒号结束。

6.2 使用表格

表格其实跟面向对象有一定联系，大部分时候表格中的一行相当于一个对象，表格中的列相当于对象的属性（字段），表格和面向对象组织数据的方式本质上是一致的。技术型文档中表格一般用来组织与数字有关的内容，当然也有例外，就像前面章节中用到的表格，纯粹是为了组织文本内容。

下面是在技术型文档中，使用表格时可以参考的一些经验：

1. 组织数字相关内容时，一定要用表格（大部分人可能已经有这个意识）；
2. 组织结构化类型的文本内容时，尽量用表格；
3. 每个表格都应该配一个表格标题，简要说明表格内容；
4. 文档中的表格应具备一致的样式和风格，比如标题字体、背景填充等。

在技术型文档中使用表格组织文本内容时，需要控制每个单元格的文本长度。一般情况下建议单元格中只使用短语，如果必须要用段落，也应该控制段落中句子数量（一般建议不超过2~3句）。下面是错误使用表格来组织文本内容的示范：

表6-1 三种编程语言介绍

序号 语言 介绍

1	C	C语言由贝尔实验室发明于1969至1973年，是一种编译型计算机编程语言。它运行速度快、效率高、使用灵活，常被用于计算机底层驱动以及各种语言编译器的开发。C语言是一种面向过程的编程语言，同时它的语法相对来讲较复杂，新人入门门槛比较高。
2	C++	C++语言发明于1979年，是一种编译型计算机编程语言。它衍生自C语言，继承了C语言的一些特性，比如使用指针直接访问内存，同时它也支持面向对象编程，提升了代码的可复用性、可扩展性以及灵活性。由于C++继承了C的大部分语法，再加上本身具备复杂的类型系统以及泛型编程等语言特性，新人入门门槛也比较高。
3	Python	Python语言发明于1991年，是一种解释型计算机编程语言，因此运行速度相对要慢。Python除了支持面向对象编程之外，还支持函数式编程，它语法简单，更贴近人类自然语言，新人入门门槛较低。Python是目前人工智能领域最热门的语言，对应的工具库非常丰富。

上面是以表格的形式来介绍C、C++以及Python三种编程语言，但是在“介绍”那一列中的文本内容太长，我们可以换一种表达方式：

表6-2 C vs C++ vs Python

C C++ Python

由AT&T 贝尔实验室发明于1969至1973年	由BJarne Struistrup发明于1979年	由Guido van Rossum发明于1991年
语法比较复杂，新人入门门槛高	语法比较复杂，新人入门门槛较高	语法简单，贴近人类自然语言，新人入门门槛低
编译型语言	编译型语言	解释型语言
支持面向过程编程	支持面向过程、面向对象编程	支持面向过程、面向对象、函数式编程
偏底层、运行速度快、使用灵活	继承了C语言的一些特性，在其基础之上还支持面向对象等特性	语法简单，学习难度低
一般用于驱动、编译器、嵌入式或者其他偏向硬件层面的开发	一般用于游戏前后端、PC客户端的开发	一般用于数据科学、人工智能相关开发

上面表格一共还是3列，但是现在每列代表一种编程语言，列中的每个单元格是对该语言的描述，描述内容都比较精简。如果你想继续补充内容，可以对应地增加行即可。表格的组织方式有多种多样，行可以变成列、列可以变成行，并没有严格的限制。我们只需要找一个适合自己的方式，比如上面这种每列代表一种语言，是因为该场景需要介绍的编程语言只有三种，如果数量再多点（或者数量不确定，后期会继续增加），那么表格宽度就不太够、这种组织方式就不再合适。

7 一图胜千言

人类在发明文字媒介之前，用的是图形符号。图像（或图形、图片）是所有内容表达方式中最直观的一种，同时也能提升读者的阅读兴趣。有人专门做过研究：在文档中增加图像能提升读者对文档的喜爱程度，不管这个图像跟文档内容本身是否有关系（论文链接）。也就是说，哪怕在文档中插入无关紧要的图像，读者也更愿意去尝试阅读文档中其他的内容。我们平时看别人演示PPT时，如果发现整页都是文字描述，大概率就不会有认真去听的欲望。下面是一段对双向链表的文字描述：

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

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

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

所有内容表达方式中最直观的一种，同时也能提升读者的阅读兴趣。有人专门做过研究：在文档中增加图像能提升读者对文档的喜爱程度，不管这个图像跟文档内容本身是否有关系（论文链接）。也就是说，哪怕在文档中插入无关紧要的图像，读者也更愿意去尝试阅读文档中其他的内容。我们平时看别人演示PPT时，如果发现整页都是文字描述，大概率就不会有认真去听的欲望。下面是一段对双向链表的文字描述：

[外链图片转存中…(img-cHDLftsF-1715564654998)]
[外链图片转存中…(img-9SbYXvPa-1715564654999)]
[外链图片转存中…(img-0HjLOPiU-1715564655000)]

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

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

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