如何写好一篇技术文档?

本文参考自document-style-guide

文档体系

结构

• 简介
• 快速上手

• 入门篇

  • 环境准备
  • 安装
  • 设置
• 进阶篇
• API

标题

层级

标题分为四级。

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

注意的问题

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

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

# 一级标题

### 三级标题

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

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

## 二级标题A

### 三级标题A

## 二级 标题

（3）谨慎使用四级标题，尽量避免出现，保持层级的简单。

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

示例：下面的文章结构中使用项目列表。

### 三级标题

* A
* B
* C

文本

字间距

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

错误：本文介绍如何规范编写markdown文档。

正确：本文介绍如何规范编写 markdown 文档。

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

正确：2020年12月17日，我正在编写我的第68篇技术博客。

正确：2020 年 12 月 17 日，我正在编写我的第 68 篇技术博客。

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

错误：他使用的是 ubuntu 。

正确：他使用的是 ubuntu。

句子

（1）避免使用长句，使用简单句和并列句。

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

复合句：那个昨天生病的人没有参加会议。【不推荐】

（2）使用肯定句进行表达，不适用否定句表达。

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

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

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

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

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

写作风格

（1）使用主动语态。

错误：假如此软件未被安装。

正确：假如尚未安装这个软件。

（2）使用正式的语言风格（看个人风格吧，不过官方的技术文档必须正式，个人博客适当可以幽默点）。

错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！

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

英文处理

（1）表示中文时，英文省略号（...）应改为中文省略号（......）。

英文：5 minutes later⋯

中文：5 分钟过去了……　【调整为中文输入法，然后按Shift + 6】

（2）英文书名与中文书名。

英文：He published an article entitled "The Future of the Aviation".

中文：他发表了一篇名为《航空业的未来》的文章。

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

IOC（International Olympic Committee，国际奥林匹克委员会）。后面直接使用　”IOC“。

段落

原则

• 一个段落只能有一个主题，或一个中心句子。
• 段落的中心句子放在段首，对全段内容进行阐述。后面陈述的句子为核心句服务。
• 一个段落的长度不能超过 7 行，最佳段落长度小于等于 4 行。
• 段落之间使用一个空行隔开。

引用

引用第三方内容时，应标明出处。

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

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

[本文转载自 WikiQuote](https://github.com/ruanyf/document-style-guide/blob/master/docs/paragraph.md)

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

本文部分图片来自 Wikipedia