技术文档写作指南（2）

上一篇：技术文档写作指南（1）

4. 数值

半角数字

数字一律使用半角形式，不得使用全角形式。

错误：这件商品的价格是１０００元。
正确：这件商品的价格是 1000 元。

千分号

数值为千位以上，应添加千分号（半角逗号）。

XXX 公司的实收资本为 RMB1,258,000。

对于 4~6 位的数值，千分号是选用的，比如 1000 和 1,000 都可以接受。对于 7 位及以上的数值，千分位是必须的。
多位小数要从小数点后从左向右添加千分号，比如 4.234,35。

货币

货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。

$1,000
1,000 美元

数值范围

表示数值范围时，用~连接。参见《标点符号》一节的“连接号”部分。
带有单位或百分号时，两个数字都要加上单位或百分号，不能只加后面一个。

错误：123~234kg
正确：132kg~234kg

错误：67~89%
正确：67%~89%

变化程度的表示法

数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。

增加到过去的两倍
（过去为一，现在为二）
增加了两倍
（过去为一，现在为三）

不能用“降低N倍”或“减少N倍”的表示法，要用“降低百分之几”或“减少百分之几”。因为减少（或降低）一倍表示数值原来为一百，现在等于零。

5. 标点符号

原则

• 中文语句的标点符号，均应该采取全角符号，这样可以保证视觉的一致。
• 如果整句为英文，则该句使用英文/半角标点。
• 句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。

句号

中文语句中的结尾处应该用全角句号（。）。
句子末尾用括号加注时，句号应在括号之外。

错误：关于文件的输出，请参照第 1.3 节（见第 26 页。）
正确：关于文件的输出，请参照第 1.3 节（见第 26 页）。

逗号

逗号，表示句子内部的一般性停顿。
注意避免“一逗到底”，即整个段落除了结尾，全部停顿都使用逗号。

顿号

句子内部的并列词，应该用全角顿号（、）分隔，而不用逗号，即使并列词是英语也是如此。

错误：我最欣赏的科技公司有 Google，FaceBook，腾讯，阿里和百度等。
正确：我最欣赏的科技公司有 Google、FaceBook、腾讯、阿里和百度等。

英文句子中，并列词语之间使用半角逗号（，）分隔。

例句：Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.

分号

分号；表示复句内部并列分句之间的停顿。

引号

引用时，应该使用全角双引号（“”），注意前后双引号不同。

例句：许多人都认为客户服务的核心是“友好”和“专业”。

引号里面还要用引号时，外面一层用双引号，里面一层用单引号（‘’），注意前后单引号不同。

例句：鲍勃解释道：“我要放音乐，可萨利说，‘不行！’。”

圆括号

补充说明时，使用全角圆括号（），括号前后不加空格。

例句：请确认所有的连接（电缆和接插件）均安装牢固。

冒号

全角冒号（：）常用在需要解释的词语后边，引出解释和说明。

例句：请确认以下几项内容：时间、地点、活动名称，以及来宾数量。

表示时间是，应使用半角冒号:。

例句：早上 8:00

省略号

省略号……表示语句未完、或者逾期的不连续。它占两个汉字空间、包含六个省略点，不要使用。。。或...等非标准形式。
省略号不应与“等”这个词一起使用。

错误：我们为会餐准备了香蕉、苹果、梨...等各色水果。
错误：我们为会餐准备了各色水果，有香蕉、苹果、梨……
正确：我们为会餐准备了香蕉、苹果、梨等各色水果。

感叹号

因使用平静的语气叙述，尽量避免使用感叹号!。
不得多个感叹号连用，比如!!!和！！。

破折号

破折号——一般用于进一步解释。
破折号应占两个汉字的位置。如果破折号本身只占一个汉字的位置，那么前后应该留出一个半角空格。

连接号

连接号用于连接两个类似的词。
以下场合应该使用直线连接号（-）,占一个半角字符的位置。

• 两个名词的复合
• 图表编号

例句：氧化-还原反应
例句：图 1-1

以下场合应该使用波浪连接号（～）,占一个全角字符的位置。

• 数值范围（例如日期、时间或数字）

例句：2009 年～2011 年

注意，波浪连接号前后两个值都应该加上单位。
波浪连接号也可以用汉字“至”代替。

例句：周围温度：-20℃ 至 -10℃

6. 文档体系

结构

软件手册是一部完整书，建议采用下面的结构。

• 简介（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