技术文章写作规范

来源： GitHub - ruanyf/document-style-guide: 中文技术文档的写作规范，by阮一峰

前言

最近在写文章会想一篇好的文章是不是和写语文作文一样有规范呢？所以就在网上看到阮一峰老师的写的这篇中文技术文档写作规范，觉得真的写得很好，这里就和大家分享一下。

但是阮老师写的是技术文档规范，个人觉得文章的话如果整得太严肃的话或许不太好，不过一些结构，表达还是要注意得，像代码用 md 代码块， uml 图等等会好一点，当然这是个人爱好，这里给大家转载一些我觉得在平时写文章要注意一下的几个点，有兴趣的可以直接去看阮老师的正文！

标题

层级

标题分为四级。

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

下面是示例。

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

原则

（1）一级标题下，不能直接出现三级标题。

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

# 一级标题

### 三级标题

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

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

## 二级标题 A

### 三级标题 A

## 二级标题 B

（3）下级标题不重复上一级标题的名字。

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

## 概述

### 概述

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

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

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

结构一

### 三级标题

#### 四级标题 A

#### 四级标题 B

#### 四级标题 C

结构二

### 三级标题

**（1）A**

**（2）B**

**（3）C**

文本

字间距

（1）全角中文字符与半角英文字符之间，应有一个半角空格。

错误：本文介绍如何快速启动Windows系统。

正确：本文介绍如何快速启动 Windows 系统。

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

正确：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。

正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。

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

正确：今年我国经济增长率是6.5%。

正确：今年我国经济增长率是 6.5%。

（3）英文单位若不翻译，单位前的阿拉伯数字与单位符号之间，应留出适当的空隙。

例1：一部容量为 16 GB 的智能手机

例2：1 h = 60 min = 3,600 s

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

错误：他的电脑是 MacBook Air 。

正确：他的电脑是 MacBook Air。

句子

（1）避免使用长句。

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

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

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

逗号分割的长句，总长度不应该超过 100 字或者正文的 3 行。

（2）尽量使用简单句和并列句，避免使用复合句。

并列句：他昨天生病了，没有参加会议。

复合句：那个昨天生病的人没有参加会议。

（3）同样一个意思，尽量使用肯定句表达，不使用否定句表达。

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

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

（4）避免使用双重否定句。

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

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

变化程度的表示法

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

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

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

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

降低到百分之八十
（定额是一百，现在是八十）

降低了百分之八十
（原来是一百，现在是二十）

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

参考链接

• 产品手册中文写作规范, by 华为
• 写作规范和格式规范, by DaoCloud
• 技术写作技巧在日汉翻译中的应用, by 刘方
• 简体中文规范指南, by lengoo
• 文档风格指南, by LeanCloud
• 豌豆荚文案风格指南, by 豌豆荚
• 中文文案排版指北, by sparanoid
• 中文排版需求, by W3C
• 为什么文件名要小写？, by 阮一峰
• Google Developer Documentation Style Guide, by Google