2016年10月18日星期二

阮一峰的网络日志

阮一峰的网络日志

中文技术文档的写作规范

Posted: 17 Oct 2016 05:19 PM PDT

很多人说，不知道怎么写文档，都是凭着感觉写。

网上也很少有资料，教你写文档。这已经影响了中文软件的发展。

英语世界里，文档非常受重视，许多公司和组织都有自己的文档规范，清楚地规定写作要求，比如微软、MailChimp、Apple、Yahoo、docker、Struts 等等（维基百科有一份完整的清单）。中文的也有不少，但都不令人满意，要么太简单，要么不太适用。

我就动手，参考上面的规范，也结合自己的实践，总结了一份简单的《中文技术文档的写作规范》。

  1. 标题
  2. 文本
  3. 段落
  4. 数值
  5. 标点符号
  6. 章节结构

我希望，这样可以抛砖引玉，让更多人重视文档，进而真正出现大家普遍接受的文档规范。

下面是关于写作风格的一个片段。欢迎提交 Issue 和 PR 补充。

=================================

写作风格

（摘自《中文技术文档的写作规范》）

如果使用了被动语态，应考虑更改为主动语态。

 错误：假如此软件尚未被安装，  正确：假如尚未安装这个软件，

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

 错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！  正确：无法参加本次活动，我深感遗憾。

用对"的"、"地"、"得"。

 她露出了开心的笑容。 （形容词＋的＋名词）  她开心地笑了。 （副词＋地＋动词）  她笑得很开心。 （动词＋得＋副词）

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

 错误：从管理系统可以监视中继系统和受其直接控制的分配系统。  正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。

名词前不要使用过多的形式词。

 错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。  正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。

句子的长度尽量保持在20个字以内；20～29个字的句子，可以接受；39～39个字的句子，语义必须明确，才能接受；多于40个字的句子，在任何情况下都不能接受。

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

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

 错误：请确认没有接通装置的电源。  正确：请确认装置的电源已关闭。

避免使用双重否定句。

 错误：没有删除权限的用户，不能删除此文件。  正确：用户必须拥有删除权限，才能删除此文件。

（正文完）

====================================

下面是推广时间。不过我想先说一些题外话。

如果你经常来这里，可能会注意到，有的文章结尾有市场推广信息。上一篇文章就是这样，我的《财新周刊》专栏写到了 Udacity，他们正好在推广纳米学位，就在那篇文章后面做了一个广告。有的朋友因此指责我写"软文"，这不是事实。

事实是，我的博客上没有一篇是"软文"，尽管一直有人来问价格。所有的文章都是真实想法，都是我真心想分享的东西。每一个来访问的读者，我都当作是朋友，不会把一篇广告伪装成正常的文章，去欺骗朋友。这一直是我做人的信条，不会为了一点点钱，就把这么多年的坚持都抛弃了。

推广活动都放在文章的结尾，明确注明是推广，并且我只接受那些我认可的产品。对我来说，这点收入可以补贴服务器支出；对许多读者来说，有些信息可能非常有用，比如下面这条。

====================================

今天推广的主角是"海棠学院"，一个前端开发的在线教育平台。

创始人小河就是培训班出身，通过自身努力进入百度，深知自学者的苦恼：企业不愿意要培训班出来的学生，而学生不知道应该选哪一家培训机构。他创业的时候，立志要做一家靠谱的、有信誉、有口碑的在线教育公司。

"海棠学院"的很多讲师都有百度背景，开发过用户上亿的产品。为了做出最容易学会的课程，他们反复尝试，不惜放弃已经录好的500多个课时，推倒重来。功夫不负有心人，"海棠学院"现在已经取得了很好的成绩。

  • 两门免费课在腾讯课题排名第一和第三，已经稳定了两个月。
  • 在网易云课堂，百度传课等平台也是名列前茅。
  • 区别于别家，他们免费课的评价与报名人数真真实实，没有水分。

更难得的是，"海棠学院"是工程师的创业项目，甚至都没有市场销售人员，完全靠用户的口碑来推广。如果课程质量不好，他们马上就完蛋了。

现在，为了发展更多的用户，也是因为对课程很有信心，他们搞了一个活动，抛弃 "先付费、再学习" 的模式，让用户零成本体验他们提供高质量培训。

  1. 只需要缴纳 99 元，即可感受海棠学院一周的课程，与正式学员享受一模一样的待遇（录播+直播+教学监管+技术辅导）。
  2. 一周后，如果觉得不满意，99 元可以退款。
  3. 如果想继续学下去，已经缴纳的 99 元可以抵扣学费，并且学费还可以再优惠 900 元。也就是说，参加这个活动比起直接报名，可以一共节省 999 元的学费。
  4. 我的读者还可以使用独家优惠码"ruanyifeng"，学费再抵扣 300 元。

整个课程一共需要 4.5 个月左右，涉及前端开发的各个方面，目标是通过一次系统的培训，你就能从事前端开发这项工作。遇到不懂的地方，可以重学，他们保证让你学会。

想从事前端开发，却不知道从何学起的朋友，不要错过这个机会。只需99元，就可以感受一下专业级、全方位的培训服务，如果不满意，99元还可以退款。

这个活动10月31日截止，因为当天就开课了，后面就恢复原价了。现在 就点击这里了解详情吧。

（完）

文档信息
发帖者 时间：