如何撰写技术文档

本文最后更新于2022年04月30日，阅读时请注意时效。

围绕“高效精准解决问题”简单介绍一下撰写技术文档的一些注意事项。

想清楚要写的是什么：

有了明确的目的之后，下笔的激败脉络就会变得清明纤颤晰。

想清楚写给谁看。如果是一篇面向新手的指导，那么其中的高级话题就可以不做展开；而在面向经验用户的文档中，一些基础知识就可以适当省略。相反，如果一篇讲解高级话题的文档对过于基础的知识进行了太多说明，文章就会变得冗长，读者也会难以从中高效的获取信息。

对读者水平的一些基础假设，可以参考 阅读技术文档需要具备的能力 。竖知

在前两点的基础上，将篇幅大量分给文章解决的独特的问题上。对于很容易就能搜索到的内容可以一笔带过。提醒自己不要把技术文档写成wiki。这一条可以节约大量时间。

注明出处/理由可以让一篇文章看起来像是有据可循技术文档而不是某种神秘而不可告人的魔法，这些信息往往可以帮助读者弄清楚文中的解决方案是否适合自己。

另外，被问题卡住的新手很多时候是因为找不到好的信息源，通过注明官方文档的位置/推荐一个好的论坛的方式往往可以让读者获得更多文章以外的开阔视野的机会，也可以帮助读者养成更好的思考方式。

提醒自己，即使是自认为“客观的描述”也十分容易失真、让人困惑。在关键位置放上“原文”，这样即使在描述上存在理解的差异，读者也可以根据这些信息复现文中的实验。

文本的通用性很强，文本的阅读速度很快，文本方便搜索。

读者的时间很宝贵，作者的时间也很宝贵，少些一点可以节约时间，参照unix “do one thing well” 的哲学，一篇重点突出的小文已经够用了。

引用：

the art of unix programming - page 12: "Make each program do one thing well."

标题分为四级。

下面是示例。

（1）一级标题下，不能直接出现三级标题。

示例：下面的文章结构，缺少二级标题。

（2）标题要避免孤立编号（即同级标题只有一个）。

示例：下面的文章结构， 二级标题 A 只包含一个三级标题，完全可以省略 三级标题 A 。

（3）下级标题不重复上一级标题的名字。

示例：下面的文章结构，二级标题与下属的三级标题同名，拍迅建议避免。

（4）谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节。

如果三级标题下有并列性的内容，建议只使用项目列表（Item list）。

示例：下面的结构二要好于结构一。后者适用的场景，主要是较长篇幅的内容。

全角中文字符与半角英文字符之间，应有一个半角空格。

全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。

半角的百分号，视同阿拉伯数字。

英文单位若不翻译，单位前的阿拉伯数字与单位间不留空格。

半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。

1、尽量不使用被动语态，改为使用主动语态。

2、不使用非正式的语言风格。

3、不使用冷僻、生造或者文言文的词语，而要使用现代汉语的常用表达方式。

4、用对“的”、“地”、“得”。

5、使用代词时（比如“其”、“该”、“此”、“这”等词），必须明确指代的内容，保证只有一个含义。

6、名词前不要使用过多的形容词。

7、不咐如包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，在任何情况下都不能接受。

8、同样一个意思，尽量使用肯定句表达，不使用否定句表达。

9、避免使用双重否定句。

英文原文如果使用了复数形式，翻译成中文时，应该将其还原为单数形式。

外文缩写可以使用半角圆点( . )表示缩写。

表示中文时，英文省略号（ ⋯ ）应改为中文省略号（ …… ）。

英文书名或电影名改用中文表达时，双引号应改为书名号。

第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。

专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。

引用第三方内容时，应注明出处。

使用外部图片时，必须在图片下方或文末标明来源。

数字一律使用半角形式，不得使用全角形式。

数值为千位以上，应添加千分号（半角逗号）。

对于 4 ～ 6 位的数值，千分号是选用的，比如 1000 和 1,000 都可以接受。对于7位及以上的数值，千分号是必须的。

多位小数要从小数点后从左向右添加千分号，比如 4.234,345 。

货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。

表示数值范围时，用 ～ 连接。参见《标点符号》一节的“连接号”部分。

带有单位或百分号时，两个数字都要加上单位或百分号，不能只加后面一个。

数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。

数字的减少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。

不能用“降低N倍”或“减少N倍”的表示法，要用“降低百分之几”或“减少百分之几”。因为减少（或降低）一倍表示数值原来为一百，现在等于零。

中文语句中的结尾处应该用全角句号（ 。 ）。

句子末尾用括号加注时，句号应在括号之外。

逗号 ， 表示句子内部的一般性停顿。

注意避免“一逗到底”，即整个段落除了结尾，全部停顿都使用逗号。

句子内部的并列词，应该用全角顿号( 、 ) 分隔，而不用逗号，即使并列词是英语也是如此。

英文句子中，并列词语之间使用半角逗号（ , ）分隔。

分号 ； 表示复句内部并列分句之间的停顿。

引用时，应该使用全角双引号（ “ ” ），注意前后双引号不同。

引号里面还要用引号时，衡贺启外面一层用双引号，里面一层用单引号（ ‘ ’ ），注意前后单引号不同。

补充说明时，使用全角圆括号 （） ，括号前后不加空格。

全角冒号（ ： ）常用在需要解释的词语后边，引出解释和说明。

表示时间时，应使用半角冒号（ : ）。

省略号 …… 表示语句未完、或者语气的不连续。它占两个汉字空间、包含六个省略点，不要使用 。。。 或 ... 等非标准形式。

省略号不应与“等”这个词一起使用。

应该使用平静的语气叙述，尽量避免使用感叹号 ！ 。

不得多个感叹号连用，比如 ！！ 和 !!! 。

破折号 ———— 一般用于进一步解释。

破折号应占两个汉字的位置。如果破折号本身只占一个汉字的位置，那么前后应该留出一个半角空格。

连接号用于连接两个类似的词。

以下场合应该使用直线连接号（ - ），占一个半角字符的位置。

以下场合应该使用波浪连接号（ ～ ），占一个全角字符的位置。

注意，波浪连接号前后两个值都应该加上单位。

波浪连接号也可以用汉字“至”代替。

软件手册是一部完整的书，建议采用下面的结构。

下面是两个真实范例，可参考。

文档的文件名不得含有空格。

文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。

文件名建议只使用小写字母，不使用大写字母。

为了醒目，某些说明文件的文件名，可以使用大写字母，比如 README 、 LICENSE 。

文件名包含多个单词时，单词之间建议使用半角的连词线（ - ）分隔。

查看原文

---