技术文档规范

标题

  • 标题逐级出现,避免跨级
  • 避免同级标题只有一个
  • 谨慎使用四级标题,保持层级简单

文本

字间距

  • 中文和英文之间加空格
正确:编程入门避免不了 hello world 的洗礼。
错误:编程入门避免不了hello world的洗礼。

写作风格

  • 使用主动语态,避免被动语态
主动:修改data字段为string类型。
被动:data字段被修改为string类型。
  • 使用正式的语句,避免非正式口语

  • 的、地、得

  • 控制语句长度,建议<20字,避免>40字

  • 使用肯定语句,避免否定语句

  • 不使用双重否定语句

段落

原则

  • 一个段落只能有一个主题,或一个中心句子。
  • 段落的中心句子放在段首,对全段内容进行概述。后面陈述的句子为核心句服务。
  • 一个段落的长度不能超过七行,最佳段落长度小于等于四行。
  • 段落的句子语气要使用陈述和肯定语气,避免使用感叹语气。
  • 段落之间使用一个空行隔开。
  • 段落开头不要留出空白字符。

引用

引用第三方内容时,应注明出处。

One man’s constant is another man’s variable. — Alan Perlis

如果是全篇转载,请在全文开头显著位置注明作者和出处,并链接至原文。

本文转载自 WikiQuote

使用外部图片时,必须在图片下方或文末标明来源。

本文部分图片来自 Wikipedia

数值

半角数字

阿拉伯数字一律使用半角形式,不得使用全角形式。

错误:这件商品的价格是1000元。

正确:这件商品的价格是 1000 元。

千分号

数值为千位以上,应添加千分号(半角逗号)。

XXX 公司的实收资本为 ¥1,258,000 人民币。

对于 4 位的数值,千分号是选用的,比如10001,000都可以接受。对于 4 位以上的数值,应添加千分号。

货币

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

$1,000
1,000 美元

英文的货币名称,建议参考国际标准 ISO 4217。

数值范围

表示数值范围时,用波浪线()或一字线()连接。参见《标点符号》一节的“连接号”部分。

带有单位或百分号时,两个数字建议都要加上单位或百分号。

132 kg~234 kg

67%~89%

变化程度的表示法

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

增加到过去的两倍
(过去为一,现在为二)

增加了两倍
(过去为一,现在为三)

数字的减少要使用“降低了”、“降低到”。“了”表示增量,“到”表示定量。

降低到百分之八十
(定额是一百,现在是八十)

降低了百分之八十
(原来是一百,现在是二十)

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

标点符号

原则

(1)中文语句的标点符号,均应该采取全角符号,这样可以与全角文字保持视觉的一致。

(2)如果整句为英文,则该句使用英文/半角标点。

(3)句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。

(4)点号(句号、逗号、顿号、分号、冒号)不得出现在标题的末尾,而标号(引号、括号、破折号、省略号、书名号、着重号、间隔号、叹号、问号)可以。

句号

(1)中文语句的结尾处应该用全角句号()。

(2)句子末尾用括号加注时,句号应在括号之外。

错误:关于文件的输出,请参照第 1.3 节(见第 26 页。)

正确:关于文件的输出,请参照第 1.3 节(见第 26 页)。

逗号

(1)逗号()表示句子内部的一般性停顿。

(2)注意避免“一逗到底”,即整个段落除了结尾,全部停顿都使用逗号。

顿号

(1)句子内部的并列词,应该用全角顿号() 分隔,而不用逗号,即使并列词是英语也是如此。

错误:我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。

正确:我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。

(2)英文句子中,并列词语之间使用半角逗号(,)分隔。

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

(3)中文句子内部的并列词,最后一个尽量使用()来连接,使句子读起来更加连贯,下面两个句子都可以,第二个更优。

正确:我最欣赏的科技公司有 Google、Facebook、腾讯、阿里,以及百度等。

正确:我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。

分号

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

引号

(1)引用时,应该使用全角双引号(“ ”),注意前后双引号不同。

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

(2)引号里面还要用引号时,外面一层用双引号,里面一层用单引号(‘ ’),注意前后单引号不同。

例句:鲍勃解释道:“我要放音乐,可萨利说,‘不行!’。”

括号

(1)补充说明时,使用全角圆括号(()),括号前后不加空格。

例句:请确认所有的连接(电缆和接插件)均安装牢固。

(2)几种括号的中英文名称。

英文 中文
{ } braces 或 curly brackets 大括号
[ ] square brackets 或 brackets 方括号
< > angled brackets 尖括号
( ) parentheses 圆括号

冒号

(1)全角冒号()常用在需要解释的词语后边,引出解释和说明。

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

(2)表示时间时,应使用半角冒号(:)。

例句:早上 8:00

省略号

(1)省略号(……)表示语句未完、或者语气的不连续。

(2)省略号占两个汉字空间、包含六个省略点,不要使用。。。...等非标准形式。

(3)省略号不应与“等”这个词一起使用。

错误:我们为会餐准备了香蕉、苹果、梨…等各色水果。

正确:我们为会餐准备了各色水果,有香蕉、苹果、梨……

正确:我们为会餐准备了香蕉、苹果、梨等各色水果。

感叹号

(1)应该使用平静的语气叙述,尽量避免使用感叹号()。

(2)不得多个感叹号连用,比如!!!!!

破折号

(1)破折号————一般用于进一步解释。

(2)破折号应占两个汉字的位置。如果破折号本身只占一个汉字的位置,那么前后应该留出一个半角空格。

例句:直觉————尽管它并不总是可靠的————告诉我,这事可能出了些问题。

例句:直觉 —— 尽管它并不总是可靠的 —— 告诉我,这事可能出了些问题。

连接号

(1)连接号用于连接两个类似的词。

(2)以下场合应该使用直线连接号(-),占一个半角字符的位置。

  • 两个名词的复合
  • 图表编号
例句:氧化-还原反应

例句:图 1-1

(3)数值范围(例如日期、时间或数字)应该使用波浪连接号()或一字号(),占一个全角字符的位置。

例句:2009 年~2011 年

注意,波浪连接号前后两个值都建议加上单位。

(4)波浪连接号也可以用汉字“至”代替。

例句:周围温度:-20 °C 至 -10 °C

文档结构

  • 简介(Introduction): [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
  • 快速上手(Getting Started):[可选] [文件] 如何最快速地使用产品
  • 入门篇(Basics): [必备] [目录] 又称”使用篇“,提供初级的使用教程
    • 环境准备(Prerequisite):[必备] [文件] 软件使用需要满足的前置条件
    • 安装(Installation):[可选] [文件] 软件的安装方法
    • 设置(Configuration):[必备] [文件] 软件的设置
  • 进阶篇(Advanced):[可选] [目录] 又称”开发篇“,提供中高级的开发教程
  • API(Reference):[可选] [目录|文件] 软件 API 的逐一介绍
  • FAQ:[可选] [文件] 常见问题解答
  • 附录(Appendix):[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
    • Glossary:[可选] [文件] 名词解释
    • Recipes:[可选] [文件] 最佳实践
    • Troubleshooting:[可选] [文件] 故障处理
    • ChangeLog:[可选] [文件] 版本说明
    • Feedback:[可选] [文件] 反馈方式

参考范例:

  • Redux 手册
  • Atom 手册

文件名

文档的文件名不得含有空格。

文件名必须使用半角字符,不得使用全角字符、中文。

错误:名词解释.md

正确:glossary.md

文件名建议只使用小写字母,不使用大写字母。

  1. 可移植性:Linux 系统是大小写敏感的,而 Windows 系统和 Mac 系统正好相反,大小写不敏感。两个文件名只有大小写不同,其他都相同,跨平台就会出问题。
  2. 易读性:小写文件名通常比大写文件名更易读,驼峰命名法不适用全部是大写的缩略词。
  3. 易用性:用户文件名都采用小写,和系统自动产生的目录区分出来。grep时不需要-i参数,输入时也不需要切换大小写。
错误:TroubleShooting.md

正确:troubleshooting.md 

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

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

不佳:advanced_usage.md

正确:advanced-usage.md

参考

https://github.com/ruanyf/document-style-guide/blob/master/docs/reference.md
https://github.com/ruanyf/document-style-guide
http://www.ruanyifeng.com/blog/2017/02/filename-should-be-lowercase.html

内容转自:https://www.ruanyifeng.com/blog/2016/10/document_style_guide.html

你可能感兴趣的:(技术文档规范)