中文文档写作规范
作为一名程序员,良好的文风和良好的编程习惯同样重要。
作为一名中国区开发者,不得不面对国内技术相比英文国家滞后的事实,许多中文文档都翻译自英文。平时参加一些技术类分享的活动时,PPT、文档、README都要用中英文写,常常会很困惑一些格式如何排版比较合理,一些措辞是否适合相应场合,最近读到阮一峰老师的中文技术文档的写作规范,当即认定是一份答疑解惑的好材料,笔者认为,不止适用于技术文档,博客、胶片,都可参考。
标题
标题分为四级
一级标题:文章的标题
二级标题:文章主要部分的大标题
三级标题:二级标题下面一级的小标题
四级标题:三级标题下面某一方面的小标题
这里主要区分一级标题通常作为文章的标题,而文章大纲类标题宜使用二级标题。
另外,尽量避免单个标题的情况,谨慎使用四级标题
文本
字间距
- 全角中文字符与半角英文字符之间,应有一个半角空格。
示例:本文介绍如何快速启动 Windows 系统。
- 全角中文字符与半角阿拉伯数字之间,不需要有半角空格,必须保证风格统一。
示例:2011年5月15日,我订购了5台笔记本电脑与10台平板电脑。
- 英文单位若不翻译,单位前的阿拉伯数字与单位间不留空格。
示例:一部容量为 16GB 的智能手机
- 半角英文字符和半角阿拉伯数字,与全角标点符号之间不留空格。
示例:他的电脑是 MacBook Air。
中英文数字夹杂的情况,原则上应该让字间距显得紧凑,同时英文单词字间距规则优先。这样的排版既不张扬又不局促。
写作风格
- 尽量不使用被动语态,改为使用主动语态。
错误:假如此软件尚未被安装,
正确:假如尚未安装这个软件,
- 不使用非正式的语言风格。
- 用对“的”、“地”、“得”。
- 使用代词时(比如“其”、“该”、“此”、“这”等词),必须明确指代的内容,保证只有一个含义。
- 名词前不要使用过多的形容词。
- 同样一个意思,尽量使用肯定句表达,不使用否定句表达。
错误:请确认没有接通装置的电源。
正确:请确认装置的电源已关闭。
- 避免使用双重否定句。
错误:没有删除权限的用户,不能删除此文件。
正确:用户必须拥有删除权限,才能删除此文件
写作风格中除了一些中学老师教过的语法错误不要犯,另外就是注意表达的简洁,准确;少用形容词,避免使用否定句,不用被动语态,都是为了达到逻辑简单,阅读流畅的目的,这一点在音译汉的时候尤其值得注意。
英文处理
- 第一次出现英文词汇时,在括号中给出中文标注。此后再次出现时,直接使用英文缩写即可。
IOC(International Olympic Committee,国际奥林匹克委员会)。这样定义后,便可以直接使用“IOC”了。
- 专有名词中每个词第一个字母均应大写,非专有名词则不需要大写
“American Association of Physicists in Medicine”(美国医学物理学家协会)是专有名词,需要大写。
“online transaction processing”(在线事务处理)不是专有名词,不应大写。
英文处理除了排版问题就是大小写(容易被忽略),另外批注虽然麻烦,但是对初次接触此类技术的人来说是非常有实用价值的。
段落
- 一个段落只能有一个主题,或一个中心句子。
- 段落的中心句子放在段首,对全段内容进行概述。后面陈述的句子为核心句服务。
- 段落的句子语气要使用陈述和肯定语气,避免使用感叹语气。
- 段落之间使用一个空行隔开。
- 段落开头不要留出空白字符。
- 使用外部图片时,必须在图片下方或文末标明来源。
示例:本文部分图片来自 Wikipedia
图片来源一事,常常被忽略,值得注意。每段文字采用总分结构,是为了便于读者迅速理解作者表达的意思,说话的时候也可以借鉴,对于意图明确的对话场景,先表态,再阐述,会让听的人更容易听懂。
数值
货币
- 货币应为阿拉伯数字,并在数字前写出货币符号,或在数字后写出货币中文名称。
$1,000
1,000 美元
变化程度的表示法
数字的增加要使用“增加了”、“增加到”。“了”表示增量,“到”表示定量。
增加到过去的两倍
(过去为一,现在为二)
增加了两倍
(过去为一,现在为三)
数字的减少要使用“降低了”、“降低到”。“了”表示增量,“到”表示定量。
降低到百分之八十
(定额是一百,现在是八十)
降低了百分之八十
(原来是一百,现在是二十)
不能用“降低N倍”或“减少N倍”的表示法,要用“降低百分之几”或“减少百分之几”。因为减少(或降低)一倍表示数值原来为一百,现在等于零。
标点符号
- 中文语句中的结尾处应该用全角句号(
。
)。 - 句子内部的并列词,应该用全角顿号(
、
) 分隔,而不用逗号。英文句子中,并列词语之间使用半角逗号(,
)分隔。 - 补充说明时,使用全角圆括号
()
,括号前后不加空格。 - 省略号
……
表示语句未完、或者语气的不连续。它占两个汉字空间、包含六个省略点,不要使用。。。
或...
等非标准形式。省略号不应与“等”这个词一起使用. - 数值范围(例如日期、时间或数字)应该使用波浪连接号(
~
),占一个全角字符的位置。
示例:2009年~2011年
注意,波浪连接号前后两个值都应该加上单位。
文档体系结构
以下内容适用于代码文档。
结构
软件手册是一部完整的书,建议采用下面的结构。
- 简介(Introduction): [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
- 快速上手(Getting Started):[可选] [文件] 如何最快速地使用产品
- 入门篇(Basics): [必备] [目录] 又称”使用篇“,提供初级的使用教程
- 环境准备(Prerequisite):[必备] [文件] 软件使用需要满足的前置条件
- 安装(Installation):[可选] [文件] 软件的安装方法
- 设置(Configuration):[必备] [文件] 软件的设置
- 进阶篇(Advanced):[可选] [目录] 又称”开发篇“,提供中高级的开发教程
- API(Reference):[可选] [目录|文件] 软件 API 的逐一介绍
- FAQ:[可选] [文件] 常见问题解答
- 附录(Appendix):[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
- Glossary:[可选] [文件] 名词解释
- Recipes:[可选] [文件] 最佳实践
- Troubleshooting:[可选] [文件] 故障处理
- ChangeLog:[可选] [文件] 版本说明
- Feedback:[可选] [文件] 反馈方式
文件名
文件名必须使用半角字符,不得使用全角字符。这也意味着,中文不能用于文件名。
错误: 名词解释.md
正确: glossary.md
文件名建议只使用小写字母,不使用大写字母。
错误:TroubleShooting.md
正确:troubleshooting.md
为了醒目,某些说明文件的文件名,可以使用大写字母,比如README
、LICENSE
。
文件名包含多个单词时,单词之间建议使用半角的连词线(-
)分隔。
不佳:advanced_usage.md
正确:advanced-usage.md