很多人说，不知道怎么写文档，都是凭着感觉写。
网上也很少有资料，教你写文档。这已经影响了中文软件的发展。
英语世界里，文档非常受重视，许多公司和组织都有自己的文档规范，清楚地规定写作要求，比如微软、MailChimp、Apple、Yahoo、docker、Struts 等等（维基百科有一份完整的清单）。中文的也有不少，但都不令人满意，要么太简单，要么不太适用。
我就动手，参考上面的规范，也结合自己的实践，总结了一份简单的《中文技术文档的写作规范》。
我希望，这样可以抛砖引玉，让更多人重视文档，进而真正出现大家普遍接受的文档规范。
下面是关于写作风格的一个片段。欢迎提交 Issue 和 PR 补充。
=================================
写作风格
（摘自《中文技术文档的写作规范》）
如果使用了被动语态，应考虑更改为主动语态。
错误：假如此软件尚未被安装， 正确：假如尚未安装这个软件，
不使用非正式的语言风格。
错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！ 正确：无法参加本次活动，我深感遗憾。
用对"的"、"地"、"得"。
她露出了开心的笑容。 （形容词＋的＋名词） 她开心地笑了。 （副词＋地＋动词） 她笑得很开心。 （动词＋得＋副词）
使用代词时（比如"其"、"该"、"此"、"这"等词），必须明确指代的内容，保证只有一个含义。
错误：从管理系统可以监视中继系统和受其直接控制的分配系统。 正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。
名词前不要使用过多的形式词。
错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。 正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。
句子的长度尽量保持在20个字以内；20～29个字的句子，可以接受；39～39个字的句子，语义必须明确，才能接受；多于40个字的句子，在任何情况下都不能接受。
错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。 正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。
同样一个意思，尽量使用肯定句表达，不使用否定句表达。
错误：请确认没有接通装置的电源。 正确：请确认装置的电源已关闭。
避免使用双重否定句。
错误：没有删除权限的用户，不能删除此文件。 正确：用户必须拥有删除权限，才能删除此文件。
（正文完）
====================================
下面是推广时间。不过我想先说一些题外话。
如果你经常来这里，可能会注意到，有的文章结尾有市场推广信息。上一篇文章就是这样，我的《财新周刊》专栏写到了 Udacity，他们正好在推广纳米学位，就在那篇文章后面做了一个广告。有的朋友因此指责我写"软文"，这不是事实。
事实是，我的博客上没有一篇是"软文"，尽管一直有人来问价格。所有的文章都是真实想法，都是我真心想分享的东西。每一个来访问的读者，我都当作是朋友，不会把一篇广告伪装成正常的文章，去欺骗朋友。这一直是我做人的信条，不会为了一点点钱，就把这么多年的坚持都抛弃了。
推广活动都放在文章的结尾，明确注明是推广，并且我只接受那些我认可的产品。对我来说，这点收入可以补贴服务器支出；对许多读者来说，有些信息可能非常有用，比如下面这条。
====================================
今天推广的主角是"海棠学院"，一个前端开发的在线教育平台。
创始人小河就是培训班出身，通过自身努力进入百度，深知自学者的苦恼：企业不愿意要培训班出来的学生，而学生不知道应该选哪一家培训机构。他创业的时候，立志要做一家靠谱的、有信誉、有口碑的在线教育公司。
"海棠学院"的很多讲师都有百度背景，开发过用户上亿的产品。为了做出最容易学会的课程，他们反复尝试，不惜放弃已经录好的500多个课时，推倒重来。功夫不负有心人，"海棠学院"现在已经取得了很好的成绩。
更难得的是，"海棠学院"是工程师的创业项目，甚至都没有市场销售人员，完全靠用户的口碑来推广。如果课程质量不好，他们马上就完蛋了。
现在，为了发展更多的用户，也是因为对课程很有信心，他们搞了一个活动，抛弃 "先付费、再学习" 的模式，让用户零成本体验他们提供高质量培训。
- 只需要缴纳 99 元，即可感受海棠学院一周的课程，与正式学员享受一模一样的待遇（录播+直播+教学监管+技术辅导）。
- 一周后，如果觉得不满意，99 元可以退款。
- 如果想继续学下去，已经缴纳的 99 元可以抵扣学费，并且学费还可以再优惠 900 元。也就是说，参加这个活动比起直接报名，可以一共节省 999 元的学费。
- 我的读者还可以使用独家优惠码"ruanyifeng"，学费再抵扣 300 元。
整个课程一共需要 4.5 个月左右，涉及前端开发的各个方面，目标是通过一次系统的培训，你就能从事前端开发这项工作。遇到不懂的地方，可以重学，他们保证让你学会。
想从事前端开发，却不知道从何学起的朋友，不要错过这个机会。只需99元，就可以感受一下专业级、全方位的培训服务，如果不满意，99元还可以退款。
这个活动10月31日截止，因为当天就开课了，后面就恢复原价了。现在 就点击这里了解详情吧。
（完）
asdf 说：
这个厉害了， 兼收并蓄， 中文强大指日可待
2016年10月18日 08:38 | # | 引用
hadeser 说：
这个要
2016年10月18日 08:43 | # | 引用
MGhostSoft 说：
中文字符和阿拉伯数字之间有空格不是必须的吧？尤其是表示日期的时候，我没见过任何中文本地化的软件在数字和“年月日”这几个字之间添加空格。
2016年10月18日 09:01 | # | 引用
Kevin 说：
干货
2016年10月18日 09:05 | # | 引用
MGhostSoft 说：
“表示数值范围时，用～连接。”
这个波浪线应该是全角～还是半角 ~ ？
《标点符号》一节中有如下正确例子：
正确：关于文件的输出，请参照第1.3节（见第26页）。
为什么此处的半角阿拉伯数字与中文字符之间没有空格？
2016年10月18日 09:07 | # | 引用
余创雄 说：
阮老师，能否将您编写的《中文技文档的写作规范》发电子版给我呢?
我看了你的文章，觉得普通的办公室人员都应按此规范写作——我不是搞技术的。
[email protected]
P.s.上一篇文章关于网络文凭的讨论获益匪浅，推荐的课程也非常好，已转可能有需要的朋友。
2016年10月18日 09:15 | # | 引用
bobbyworm 说：
“数值”一章的第一个例子“XXX 公司的实收资本为RMB 1,258,000。”
如果按“文本”一章的要求，RMB与前面的汉字之间应该有空格。
2016年10月18日 09:17 | # | 引用
Ts 说：
神奇的土地上，动不动就说自己有BAT背景。。。
2016年10月18日 09:19 | # | 引用
阮一峰 说：
@MGhostSoft：
中文单位与数字之间是否要有空格？可以开个 issue，讨论一下。
句子一：体重是 68 公斤。
句子二：体重是 68公斤。
句子三：今年是 2016 年。
句子四：现在是 8点 36分。
哪种写法更规范一些？
2016年10月18日 09:21 | # | 引用
文雨 说：
总金额是 6499
我估计不少人都是想问这个的
2016年10月18日 09:22 | # | 引用
Kevin 说：
这个是Github上的动态项目，不是PDF之类的，直接看连接就可以了。
2016年10月18日 09:23 | # | 引用
阮一峰 说：
@MGhostSoft：波浪线应该占据一个全角字符的位置。这句例子，已经改掉了。
@bobbyworm：这是 bug，已经改掉了。
@余创雄：等规范稳定下来，再做成 pdf 文件。
2016年10月18日 09:26 | # | 引用
阮一峰 说：
《数值与中文单位之间是否要加空格？》请到下面的 issue 讨论。
https://github.com/ruanyf/document-style-guide/issues/2
2016年10月18日 09:41 | # | 引用
ray 说：
新语文大纲里"的"、"地"早就统一成“的”，现在的中学生应该不区分两者了
2016年10月18日 09:44 | # | 引用
Louis 说：
期待您关于微信小程序的文章
2016年10月18日 11:10 | # | 引用
ciwei 说：
峰哥牛逼，能把简单的事情规范起来。我原来怕写作，从你博客中收益良多，现在开始有兴趣了，我在学习用类似markdown的简易排版写文章
2016年10月19日 14:43 | # | 引用
行者自若 说：
另外还要考虑的是中文的独有特点，某些词语既可名词也可动词的时候，可以优先考虑动词。比如：「请对XXX做一些修改」--->「请稍微修改XXX」。
2016年10月19日 15:54 | # | 引用
陆 说：
文中“39～39个字的句子”,应该为“30~39个字的句子”吧
2016年10月20日 08:48 | # | 引用
xin 说：
正好用到，昨天整了一天的技术文档，还没有整理完，感觉最麻烦的地方还是在word的目录结构上，经常突发性地发现标题顺序都不对了，然后那么长的文档要来回检查几遍。不知道阮老师平时是怎么处理文档目录结构的？
2016年10月20日 09:41 | # | 引用
riclava 说：
厉害了，我的哥~
2016年10月21日 09:33 | # | 引用
willizm 说：
大神这篇写得有点短
2016年10月21日 13:03 | # | 引用
小小人 说：
阮老师广告费赚了不少了吧
2016年10月21日 17:04 | # | 引用
李仙 说：
阮老师，您好，一直有关注您写的文章，写的真的是很试用的内容。我是51CTO的运用工作人员，希望能转载您的文章到我们的网站，您看可以吗？
2016年10月23日 17:03 | # | 引用
jacketli 说：
写得真好！有些翻译的教程，就是需要提高这些基础文字功底。让读者更容易理解。
2016年10月24日 10:57 | # | 引用
macarole 说：
阮老师怎么没有webpack优化教程呀
2016年10月26日 11:26 | # | 引用
zzl 说：
这个事做的真是功德无量。
2016年10月26日 21:40 | # | 引用
豪翔天下 说：
确实很强大，也很正确，但是中文的语法在实际运用中，特别是用得较少的场景，很难养成习惯的
2016年10月27日 14:41 | # | 引用
肖一林 说：
很及时啊，最近想写博客，但是发现语言太难组织了。没想到这篇文章会在这时候出现。感谢
2016年10月28日 15:14 | # | 引用
木易 说：
我觉得标点符号一定要用好，避免一大整段下来都是逗号加句号。
2016年10月30日 00:51 | # | 引用
seagate 说：
段落的开头不能留有空格。
－－－－－－－－－－
话说，写作文是不是要空两格吗？
2016年11月 2日 19:03 | # | 引用
facade 说：
我对写作的标点符号非常的烦恼，编码过程中必然需要使用半角/英文，而写技术文档过程中，又存在大量的英文和中文的结合，需要中文标点，英文标点的结合。
不知道大家是如何办到的。
2016年11月 6日 17:30 | # | 引用
陆崖 说：
本来觉得文章最后那个推广还不错,但是说道百度背景就意兴阑珊了,百度给我的体验实在是差,特别是手机版
2016年11月14日 11:35 | # | 引用
茶小调 说：
以前写文档都是逗号逗号逗号逗号句号，完了。现在终于有一丢丢入门的感觉了。
2016年11月14日 18:21 | # | 引用
ZetaChow 说：
这篇文章的内容太好了。
已经转发公司所有部门负责文档编写的人员。
感谢！
2016年11月25日 15:43 | # | 引用
Melon丶 说：
我觉得阮大神有点推广什么的完全可以理解，甚至是应该的，因为大神发布的一直都是免费而有用的干货，知识不仅是力量，说得现实点，现在知识就是金钱，中国软件发展的一个问题就是大部分国人没有为知识付费的习惯，支持你 阮大神
2016年11月28日 18:32 | # | 引用
LarryZeal 说：
本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。
改成：
本产品适用于多种体系结构：无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。
是否更恰当？
2016年12月 7日 12:44 | # | 引用
hudk 说：
句子的长度尽量保持在20个字以内；20～29个字的句子，可以接受；39～39个字的句子，语义必须明确，才能接受；多于40个字的句子，在任何情况下都不能接受。
应该是30～39
2016年12月14日 23:36 | # | 引用
SnowOnion 说：
@ray
不信。请求来源
>>ray 说：
>>新语文大纲里"的"、"地"早就统一成“的”，现在的中学生应该不区分两者了
2016年12月22日 22:38 | # | 引用
yinfei 说：
“的”的释义
[5]副词尾，同“地2”。
2016年12月23日 17:16 | # | 引用
国栋 说：
好东西，争取向规范靠拢。
2017年1月 6日 16:51 | # | 引用
张森Vinson 说：
支持峰哥。
英文的规范可以拿来参考：
1，数字后面跟单位的话，空一格。
如：桌子长 8 米。
2，标点符号紧跟前面中文文字，无空格。（这个需要加上与否？）
2017年1月18日 16:06 | # | 引用
李星阳 说：
感谢阮老师的分享
2017年1月19日 14:44 | # | 引用
Jacky 说：
个人习惯，纯数字的话，我一般不加空格，如果有英文字母，我会在和中文字之间都加入空格。也就是说，遵循微软和苹果操作系统的习惯。
2017年2月 4日 11:13 | # | 引用
Jacky 说：
我个人习惯：在中文中，全部使用中文全角标点；在英文中，全部使用英文半角标点。
1. 大量的代码快，本身是独立的，麻烦不大。
2. 两种混杂的，在哪种语境中就用哪种符号。如：
上面这个例子，括号和冒号我用中文，网址部分则全部使用英文。
上面这个例子，括号我用英文，括号里面则使用中文冒号。
3. 中英文位居不同的行或段落，遵循各自的标准。
以上内容仅用于演示符号使用习惯，内容和语法不作为文档编写标准参考。
2017年2月 4日 11:14 | # | 引用
Izual_Yang 说：
从美观角度来看，前后都加上空格比较对称。从含义的连贯性和文本编辑器自动折行角度来看，前面加个空格似乎也就够了
2017年2月 5日 23:35 | # | 引用
蓝栩液枫 说：
看了好几篇了，感觉受益非浅，留个言以示谢意。。。
2017年2月14日 22:14 | # | 引用
猪头哥 说：
去海棠学院的主页看了，真的比较丑，随手点了几个链接，居然还有404页面......
2017年2月16日 14:59 | # | 引用
Song 说：
好文章，有兴趣的朋友也话可以看看中文文案排版指北
2017年3月 6日 00:34 | # | 引用
哇咔咔！ 说：
你好，今天刚刚关注！！！
2017年4月12日 18:13 | # | 引用
杨廷兴 说：
非常佩服您的坚持、对事物的追求，技术的精湛！
好榜样！
2017年4月19日 16:40 | # | 引用
owl 说：
最近在了解docker,偶然间看到你的博客。有条理很清晰，点到为止又紧扣主题。你太厉害了。
2019年4月13日 17:10 | # | 引用
吕涛 说：
阮老师，海棠学院已经下架了吗？
2019年6月 6日 18:11 | # | 引用
Tara 说：
这个赞，补充语文知识
2019年6月14日 13:25 | # | 引用
郑钰 说：
请问阮老师，有没有哪种工具，可以帮助技术写作人员在编写文档的时候自动提醒他们不符合规范了（比如使用Oxygen XML Editor）？ 就想程序员敲代码有用于检查代码规范的软件一样？
2021年3月19日 17:17 | # | 引用