关于
本文转载自《中文技术文档的写作规范》, 略有修改。
标题
谨慎地使用标题，最好不要超过四级。
文本
字间距
中文与英文
错误：本文介绍如何快速启动Windows系统。
正确：本文介绍如何快速启动 Windows 系统。
文中出现数字
文章中的数字留不留空格都可以，我更喜欢留空格。
正确：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。
正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。
英文与数字
留个空格更好。
例1：一部容量为 16 GB 的智能手机
例2：1 h = 60 min = 3,600 s
英文后跟个中文标点
不留空格。
错误：他的电脑是 MacBook Air 。
正确：他的电脑是 MacBook Air。
句子
避免使用长句
最好长短句交替，增加文字的节奏感。
错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。
正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。
尽量使用简单句和并列句，避免使用复合句
并列句：他昨天生病了，没有参加会议。
复合句：那个昨天生病的人没有参加会议。
同样一个意思，尽量使用肯定句表达
错误：请确认没有接通装置的电源。
正确：请确认装置的电源已关闭。
避免使用双重否定句
错误：没有删除权限的用户，不能删除此文件。
正确：用户必须拥有删除权限，才能删除此文件。
写作风格
避免使用被动语态
错误：假如此软件尚未被安装，
正确：假如尚未安装这个软件，
不使用非正式的语言风格
错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！
正确：无法参加本次活动，我深感遗憾。
使用常用的现代汉语表达方式
错误：这是唯二的快速启动的方法。
正确：这是仅有的两种快速启动的方法。
使用代词必须明确指代的内容
这些代词包括“其”、“该”、“此”、“这”等词
错误：从管理系统可以监视中继系统和受其直接控制的分配系统。
正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。
名词前不要使用过多的形容词
错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。
正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。
英文处理
第一次出现英文词汇要标注
第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。
IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用“IOC”了。
段落
原则
- 一个段落只能有一个主题，或一个中心句子。
- 段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为中心句子服务。
- 一个段落的长度不能超过七行，最佳段落长度小于等于四行。
- 段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。
- 段落之间使用一个空行隔开。
- 段落开头不要留出空白字符。
引用
引用第三方内容时，应注明出处。
One man’s constant is another man’s variable. — Alan Perlis
全篇转载，应在开头显著位置注明作者和出处，并链接至全文。
本文转载自 WikiQuote
使用外部图片时，必须在图片下方或文末标明来源。
本文部分图片来自 Wikipedia
数值
数值范围
表示数值范围时，用波浪线 ~ 或一字线 - 连接。
132 kg～234 kg
67%～89%
标点符号
原则
- 中文语句的标点符号，均应该采取全角符号，这样可以与全角文字保持视觉的一致。
- 如果整句为英文，则该句使用英文/半角标点。
- 句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。
- 点号（句号、逗号、顿号、分号、冒号）不得出现在标题的末尾，而标号（引号、括号、破折号、省略号、书名号、着重号、间隔号、叹号、问号）可以。
逗号
注意避免“一逗到底”，即整个段落除了结尾，全部停顿都使用逗号。
顿号
- 句子内部的并列词，应该用全角顿号(、) 分隔，而不用逗号，即使并列词是英语也是如此。
错误：我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。
正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。
- 中文句子内部的并列词，最后一个尽量使用（和）来连接，使句子读起来更加连贯，下面两个句子都可以，第二个更优。
正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里，以及百度等。
正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。
括号
几种括号的中英文名称
| 符号 | 英文 | 中文 |
|---|---|---|
{ } |
braces 或 curly brackets | 大括号 |
[ ] |
square brackets 或 brackets | 方括号 |
< > |
angled brackets | 尖括号 |
( ) |
parentheses | 圆括号 |
文档体系
文件名
- 文件名不得含有空格。
- 不要使用中文文件名。
- 文件名建议只使用小写字母，不使用大写字母。
- 文件名包含多个单词时，单词之间建议使用半角的连词线（-）分隔。
这里第 1-3 点都是为了一些兼容系考虑。
结构
软件手册的结构
- 简介（Introduction）：[必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
- 快速上手（Getting Started）：[可选] [文件] 如何最快速地使用产品
- 入门篇（Basics）：[必备] [目录] 又称“使用篇”，提供初级的使用教程
- 环境准备（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件
- 安装（Installation）：[可选] [文件] 软件的安装方法
- 设置（Configuration）：[必备] [文件] 软件的设置
- 进阶篇（Advanced)：[可选] [目录] 又称“开发篇”，提供中高级的开发教程
- API（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍
- FAQ：[可选] [文件] 常见问题解答
- 附录（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
- Glossary：[可选] [文件] 名词解释
- Recipes：[可选] [文件] 最佳实践
- Troubleshooting：[可选] [文件] 故障处理
- ChangeLog：[可选] [文件] 版本说明
- Feedback：[可选] [文件] 反馈方式
参考链接
- 简体中文规范指南 by LeanCloud
- 余光中：怎样改进英式中文？- 论中文的常态与变态 by LeanCloud
- 为什么文件名要小写？ by 阮一峰