最近我们技术老大,让我自己写一份优秀的文档,我很少写这个,但是作为技术又不得不写,几经波折之后,找到了阮一峰大神的笔记,做了参考:

中文技术文档的写作规范-转{阮一峰}-新乡seo|网站优化,网站建设_微信公众号:zeropython—昊天博客

标题

层级

标题分为四级。

  • 一级标题:文章的标题
  • 二级标题:文章主要部分的大标题
  • 三级标题:二级标题下面一级的小标题
  • 四级标题:三级标题下面某一方面的小标题

下面是示例。

原则

(1)一级标题下,不能直接出现三级标题。

示例:下面的文章结构,缺少二级标题。

(2)标题要避免孤立编号(即同级标题只有一个)。

示例:下面的文章结构,二级标题 A只包含一个三级标题,完全可以省略三级标题 A

(3)下级标题不重复上一级标题的名字。

示例:下面的文章结构,二级标题与下属的三级标题同名,建议避免。

(4)谨慎使用四级标题,尽量避免出现,保持层级的简单,防止出现过于复杂的章节。

如果三级标题下有并列性的内容,建议只使用项目列表(Item list)。

示例:下面的结构二要好于结构一。后者适用的场景,主要是较长篇幅的内容。

文本

字间距

全角中文字符与半角英文字符之间,应有一个半角空格。

全角中文字符与半角阿拉伯数字之间,有没有半角空格都可,但必须保证风格统一,不能两种风格混杂。

半角的百分号,视同阿拉伯数字。

英文单位若不翻译,单位前的阿拉伯数字与单位间不留空格。

半角英文字符和半角阿拉伯数字,与全角标点符号之间不留空格。

句子

  • 避免使用长句。句子内部不使用逗号时,总长度不应该超过 40 个字;使用逗号时,总长度不应该超过 100 字或者正文的 3 行。
  • 尽量使用简单句和并列句,避免使用复合句。

写作风格

1、尽量不使用被动语态,改为使用主动语态。

2、不使用非正式的语言风格。

3、不使用冷僻、生造或者文言文的词语,而要使用现代汉语的常用表达方式。

4、用对“的”、“地”、“得”。

5、使用代词时(比如“其”、“该”、“此”、“这”等词),必须明确指代的内容,保证只有一个含义。

6、名词前不要使用过多的形容词。

7、不包含任何标点符号的单个句子,或者以逗号分隔的句子构件,长度尽量保持在 20 个字以内;20~29 个字的句子,可以接受;30~39 个字的句子,语义必须明确,才能接受;多于 40 个字的句子,在任何情况下都不能接受。

8、同样一个意思,尽量使用肯定句表达,不使用否定句表达。

9、避免使用双重否定句。

英文处理

英文原文如果使用了复数形式,翻译成中文时,应该将其还原为单数形式。

外文缩写可以使用半角圆点(.)表示缩写。

表示中文时,英文省略号()应改为中文省略号(……)。

英文书名或电影名改用中文表达时,双引号应改为书名号。

第一次出现英文词汇时,在括号中给出中文标注。此后再次出现时,直接使用英文缩写即可。

专有名词中每个词第一个字母均应大写,非专有名词则不需要大写。

段落

原则

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

引用

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

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

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

数值

半角数字

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

千分号

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

对于 4 ~ 6 位的数值,千分号是选用的,比如10001,000都可以接受。对于7位及以上的数值,千分号是必须的。

多位小数要从小数点后从左向右添加千分号,比如4.234,345

货币

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

数值范围

表示数值范围时,用连接。参见《标点符号》一节的“连接号”部分。

带有单位或百分号时,两个数字都要加上单位或百分号,不能只加后面一个。

变化程度的表示法

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

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

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

标点符号

原则

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

句号

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

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

逗号

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

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

顿号

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

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

分号

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

引号

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

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

圆括号

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

冒号

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

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

省略号

省略号……表示语句未完、或者语气的不连续。它占两个汉字空间、包含六个省略点,不要使用。。。...等非标准形式。

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

感叹号

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

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

破折号

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

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

连接号

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

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

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

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

  • 数值范围(例如日期、时间或数字)

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

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

文档体系

结构

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

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

下面是两个真实范例,可参考。

文件名

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

文件名必须使用半角字符,不得使用全角字符。这也意味着,中文不能用于文件名。

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

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

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