中文技术文档写作规范：值得抄进肌肉记忆的规则

Sat, 26 Sep 2026 08:00:00 +0800

整理自阮一峰的《中文技术文档写作规范》（ruanyf/document-style-guide，公共领域）。原文是完整的参考手册，本文按"日常写作时最容易踩的坑"重新组织，每条规则保留原文的错误/正确对照示例。

写技术文档的人很多，写清楚的不多。原因往往不是不会写，而是没意识到：标题层级有讲究、中英文之间要加空格、“降低一倍"是数学错误、省略号不能和"等"连用。

阮一峰这份规范把这些问题全部给出了明确答案，而且它本身就是公共领域（public domain），可以直接照搬进任何团队的文档规范。下面按使用场景过一遍精华。

一、标题层级：最多四级，不许跳级

标题分为四级：一级是文章标题，二级是主要部分的大标题，三级是二级下面的小标题，四级尽量不用。

四条硬性原则：

不许跳级——一级标题下不能直接出现三级标题；
不许孤立编号——同级标题只有一个的，直接省掉这层，比如二级标题 A 下面只有三级标题 A，那三级标题 A 就该删掉；
下级不重复上级的名字——“概述"下面再来一个"概述"是不行的；
慎用四级标题——如果三级标题下有并列内容，优先用加粗的编号列表代替：

### 三级标题

**（1）A**

**（2）B**

**（3）C**

二、字与空格：一条空格规则走天下

这是最容易形成肌肉记忆的部分：

全角中文字符与半角英文字符之间，加一个半角空格：

错误：本文介绍如何快速启动Windows系统。
正确：本文介绍如何快速启动 Windows 系统。

中文与阿拉伯数字之间的空格，加不加都行，但必须全文统一：

正确：2011年5月15日，我订购了5台笔记本电脑。
正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑。

英文单位不翻译时，数字与单位之间不留空格：

错误：一部容量为 16 GB 的智能手机
正确：一部容量为 16GB 的智能手机

半角字符与全角标点之间不留空格：

错误：他的电脑是 MacBook Air 。
正确：他的电脑是 MacBook Air。

三、句子工程：长度有量化标准

规范对"长句"给出了精确的刻度，这是全篇最实用的部分之一：

不含标点的单句或逗号分隔的句子构件，尽量 20 字以内；
20～29 字可以接受；30～39 字必须语义明确才接受；
超过 40 字，任何情况下都不能接受；
逗号分隔的长句，总长不超过 100 字或正文 3 行。

对比一下：

错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器
进行动作控制的并行处理程序结构等多种体系结构。

正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是
由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。

另外几条句式原则：

用简单句和并列句，避免复合句：“他昨天生病了，没有参加会议"好过"那个昨天生病的人没有参加会议”；
同一个意思，用肯定句不用否定句：“请确认装置的电源已关闭"好过"请确认没有接通装置的电源”；
杜绝双重否定：“用户必须拥有删除权限，才能删除此文件”，而不是"没有删除权限的用户，不能删除此文件”；
主动语态优先：“假如尚未安装这个软件”，而不是"假如此软件尚未被安装”；
用对"的地得"：形容词＋的＋名词（开心的笑容），副词＋地＋动词（开心地笑了），动词＋得＋副词（笑得很开心）；
代词指代必须唯一——“从管理系统可以监视中继系统和受其直接控制的分配系统"里那个"其"指谁？改成"受中继系统直接控制的分配系统"就清楚了。

四、数值：这些错误 AI 都常犯

数字一律半角：１０００元 错，1000 元 对；
千分号：7 位及以上数值必须加（1,258,000），4～6 位可选；
货币：$1,000 或 1,000 美元；
数值范围用波浪连接号，且两边都要带单位：

错误：132～234kg
正确：132kg～234kg

错误：67～89%
正确：67%～89%

“了"表示增量，“到"表示定量：“增加到两倍"是过去 1 现在 2，“增加了两倍"是过去 1 现在 3；
永远不要写"降低 N 倍"或"减少 N 倍”——降低一倍就意味着归零，再往下没法降了。只能写"降低百分之几”。

五、标点符号：高频坑位清单

中文语句用全角标点；整句是英文的，该句用半角；
并列词用顿号，哪怕并列的是英文：

错误：我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。
正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。

省略号是六个点占两个汉字位（……），不能用 ... 或 。。。，且不能和"等"连用：

错误：我们为会餐准备了香蕉、苹果、梨…等各色水果。
正确：我们为会餐准备了香蕉、苹果、梨等各色水果。

括号加注时，句号在括号外：“请参照第 1.3 节（见第 26 页）。"；
表示时间用半角冒号：早上 8:00；
避免感叹号，更不能连用——技术文档要的是平静的语气；
破折号占两个汉字位：————，或者前后留半角空格的单字破折号 ——；
连接号分两种：名词复合和图表编号用直线 -（氧化-还原反应、图 1-1），数值范围用波浪 ～（2009 年～2011 年，也可以写"至”）。

六、段落与引用

一个段落只有一个主题，中心句子放段首；
段落不超过七行，最佳是四行以内；
段落之间空一行，段首不留空白字符；
引用第三方内容注明出处；全篇转载必须在开头显著位置注明作者和出处并链接原文；使用外部图片必须在图下或文末标明来源。

七、文档体系：软件手册的标准骨架

如果你要写的是一部完整的产品手册，规范推荐这个结构：

部分	要求	说明
简介	必备	产品和文档本身的总体说明
快速上手	可选	最快速度用起来
入门篇	必备	初级使用教程（环境准备、安装、设置）
进阶篇	可选	中高级开发教程
API	可选	API 逐一介绍
FAQ	可选	常见问题解答
附录	可选	名词解释、最佳实践、故障处理、版本说明、反馈方式

文件名也有规矩：不用空格、只用半角小写字母（README、LICENSE 除外）、多单词用连词线分隔（advanced-usage.md 而不是 advanced_usage.md）。中文不能用于文件名。

一页速查

场景	规则
中英文混排	中文与英文/数字之间加半角空格，全文风格统一
句子长度	单句 ≤20 字最佳，>40 字一律拆句
语气	肯定句、主动语态、不用感叹号、杜绝双重否定
数值范围	用～，两边都带单位
增减表述	只能"增加 N 倍”，不能"降低 N 倍”
并列词	全角顿号、
省略号	……（六点），不与"等"连用
标题	≤4 级、不跳级、不孤立编号
段落	≤7 行，中心句放段首
转载	开头显著位置注明作者与原文链接

写文档不是文学创作，清晰就是最大的美德。这份规范的建议其实可以浓缩成一句话：让读者用最少的力气获取准确的信息——空格、断句、标点这些细节，都是在为这件事服务。

本文整理自阮一峰《中文技术文档写作规范》（ruanyf/document-style-guide，公共领域），规则内容忠于原文，章节组织与速查表为本文编辑归纳。原文另附华为、LeanCloud、Google 等十份风格指南作为参考链接，感兴趣可以按图索骥。

中文排版 on 我的博客