中文技术文档的写作规范

1. 写作风格

  1. 主动语态
  2. 正式语言风格
  3. 的地得 准确
  4. 避免使用双重否定句。

1.1. 主动语态

如果使用了被动语态,应考虑更改为主动语态。

错误:假如此软件尚未被安装,

正确:假如尚未安装这个软件,

1.2. 正式语言风格

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

错误:Lady Gaga 的演唱会真是酷毙了,从没看过这么给力的表演!!!

正确:无法参加本次活动,我深感遗憾。

1.3. 的地得 准确

用对"的"、"地"、"得"。

她露出了开心的笑容。
(形容词+的+名词)

她开心地笑了。
(副词+地+动词)

她笑得很开心。
(动词+得+副词)

1.4. 指代明确

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

错误:从管理系统可以监视中继系统和受其直接控制的分配系统。

正确:从管理系统可以监视两个系统:中继系统和受中继系统直接控制的分配系统。

1.5. 名词修饰简练

名词前不要使用过多的形式词。

错误:此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。

正确:此设备必须在技师的指导下使用,且指导技师必须接受过由本公司举办的正式设备培训。

句子长度合理,尽量<30字

句子的长度尽量保持在20个字以内;20~29个字的句子,可以接受;39~39个字的句子,语义必须明确,才能接受;多于40个字的句子,在任何情况下都不能接受。

错误:本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。

正确:本产品适用于多种体系结构。无论是由一台服务器(单一节点结构),还是由多台服务器(并行处理结构)进行动作控制,均可以使用本产品。

肯定语气表示

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

错误:请确认没有接通装置的电源。

正确:请确认装置的电源已关闭。

避免双重否定

避免使用双重否定句。

错误:没有删除权限的用户,不能删除此文件。

正确:用户必须拥有删除权限,才能删除此文件。

2. 标题

2.1. 层级

标题分为四级。
一级标题:文章的标题
二级标题:文章主要部分的大标题
三级标题:二级标题下面一级的小标题
四级标题:三级标题下面某一方面的小标题
下面是示例。

2.2. 原则

(1)一级标题下,不能直接出现三级标题。
示例:下面的文章结构,缺少二级标题。

# 一级标题

### 三级标题

(2)标题要避免孤立编号(即同级标题只有一个)。
示例:下面的文章结构,二级标题 A只包含一个三级标题,完全可以省略三级标题 A。

## 二级标题 A

### 三级标题 A

## 二级标题 B

(3)下级标题不重复上一级标题的名字。
示例:下面的文章结构,二级标题与下属的三级标题同名,建议避免。

## 概述

### 概述

(4)谨慎使用四级标题,尽量避免出现,保持层级的简单,防止出现过于复杂的章节。
如果三级标题下有并列性的内容,建议只使用项目列表(Item list)。
示例:下面的结构二要好于结构一。结构一适用的场景,主要是较长篇幅的内容。
结构一

### 三级标题

#### 四级标题 A

#### 四级标题 B

#### 四级标题 C

结构二 (好)

### 三级标题

**1A**

**2B**

**3C**

3. 参考资料1


  1. 中文技术文档的写作规范。
    https://github.com/ruanyf/document-style-guide 


如果你觉得这篇文章对你有帮助,不妨请我喝杯咖啡,鼓励我创造更多!