作为一名程序员,良好的文风和良好的编程习惯同样重要。
作为一名中国区开发者,不得不面对国内技术相比英文国家滞后的事实,许多中文文档都翻译自英文。平时参加一些技术类分享的活动时,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

为了醒目,某些说明文件的文件名,可以使用大写字母,比如READMELICENSE

文件名包含多个单词时,单词之间建议使用半角的连词线(-)分隔。

不佳:advanced_usage.md

正确:advanced-usage.md