技术文档写作指南（1）
2018-08-20 本文已影响120人
蛮吉大人123
来源：阮一峰的 github
标题
层级
标题分四级。
- 一级标题：文章的标题
- 二级标题：文章主要部分的大标题
- 三级标题：二级标题下面一级的小标题
- 四级标题：三级标题下面某一方面的小标题
示例：
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
原则
- 一级标题下，不能直接出现三级标题。
# 一级标题
### 三级标题
- 标题要避免孤立编号（即同级标题只有一个）。
## 二级标题 A
### 三级标题 A
## 二级标题 B
- 下级标题不重复上一级标题的名字。
## 概述
### 概述
- 谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节。`
结构一
### 三级标题
#### 四级标题 A
#### 四级标题 B
#### 四级标题 C
结构二
### 三级标题
**（1）A**
**（2）B**
**（3）C**
文本
字间距
全角中文字符与半角英文字符之间，应有一个半角空格。
错误：本文介绍如何快速启动Windows系统。
正确：本文介绍如何快速启动 Windows 系统。
全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。
正确：2011年5月11日，我订购了5台笔记本电脑与10台平板电脑。
正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。
半角的百分号，视同阿拉伯数字。
英文单位若不翻译，单位前的阿拉伯数字与单位间不留空格。
错误：一部容量为 16 GB 的智能手机。
正确：一部容量为 16GB 的智能手机。
半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。
错误：他的电脑是 MacBook Air 。
正确：他的电脑是 MacBook Air。
句子
- 避免使用长句。句子内部不适用逗号时，总长度不应该超过 40 个字；使用逗号时，总长度不应该超过 100 字或者正文的 3 行。
- 尽量使用简单句和并列句，避免使用复合句。
写作风格
- 尽量不适用被动语态，改为使用主动语态。
错误：假如此软件尚未被安装，
正确：假如尚未安装这个软件，
- 不适用非正式的语言风格。
错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！
正确：无法参加本次活动，我深感遗憾。
- 不适用冷僻、生造或者文言文的词语，而要使用现代汉语的常用表达方式。
错误：这是唯二的快速启动的方法。
正确：这是仅有的两种快速启动的方法。
- 用对“的”、“地”、“得”。
她露出了开心的笑容。
（形容词 + 的 + 名词）
她开心地笑了
（副词 + 地 + 动词）
她笑得很开心
（动词 + 得 + 副词）
- 使用代词时（比如“其”、“该”，“此”，“这”等词），必须明确指代的内容，保证只有一个含义。
错误：从管理系统可以监视中继系统和受其直接控制的分配系统。
正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。
- 名词前不要使用过多的形容词。
错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。
正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。
- 不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20~29 个字的句子，可以接受；30~39 个字的句子，语义必须明确，才能接受；多于 40个字的句子，在任何情况下都不能接受。
错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。
正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。
- 同样一个意思，尽量使用肯定句表达，不使用否定句表达。
错误：请确认没有接通装置的电源。
正确：请确认装置的电源已关闭。
- 避免使用双重否定句。
错误：没有删除权限的用户，不能删除此文件。
正确：用户必须拥有删除权限，才能删除此文件。
英文处理
英文原文如果使用了复数形式，翻译成中文时，应将其还原为单数形式。
英文：···information stored in random access memory (RAMS)···
中文：……储存在随机存取存储器（RAM）里
外文缩写可以使用半角圆点（.）标识缩写
U.S.A.
Apple, Inc.
表示中文时，英文省略号（...）应改为中文省略号（……）。
英文：5 minutes later...
中文：5 分钟过去了……
英文书名或电影名改用中文表达时，双引号应改为书名号。
英文：He published an article entitled "The Future of the Aviation".
中文：他发表了一篇名为《航空业的未来》的文章。
第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。
IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用“IOC”了。
专有名词中每个词第一字母均应大写，非专用名词则不需要大写。
“American Association of Physicists in Medicine”（美国医学物理学家协会）是专有名词，需要大写。
“online transaction processing”（在线事务处理）不是专用名词，不应大写。
3. 段落
原则
- 一个段落只能有一个主题，或一个中心句子。
- 段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。
- 一个段落的长度不能超过七行，最佳段落长度小于等于四行。
- 段落的句子预期要使用陈述和肯定语气，避免使用感叹语气。
- 段落之间使用一个空行隔开。
- 段落开头不要留出空白字符。
引用
引用第三方内容时，应注明出处。
One man's constant is another man's variable. -- Alan Perlis
如果是全篇转载，请在全文开头显著位置注明作者和出处，并连接至原文。
本文转自 WikiQuote
使用外部图片时，必须在图片下方或文末标明来源。
本文部分图片来自 Wikipedia
下一篇：技术文档写作指南（2）
