我的 markdown 写作风格改进 ：以《中文技术文档的写作规范》为标准

[yanyue404]

对于我来说很早就使用 markdown 来写技术文档，但如何使得文章风格有好的阅读效果却知之甚少。

偶然的机会，今天重新阅读了阮一峰老师的《中文技术文档的写作规范》，发现在之前自己书写的文档实在差的很。所以在这里记录下写文档可以改进的地方，以后在写作方面有新的见解也会同步到这篇文章。

一、标题

1. 层级问题

标题分为四级。

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

（1）Github issues 中填写的标题为 h1, 因此在正文中不应再出现一级标题。

（2）层级混乱，结构不明，不可跨级别使用标题（不使用非以上四级的标题）。

（3）圆括号应使用中文输入法进行输出。

# 错误
(1) A

# 正确
（1）A

（4）参考链接应设为二级标题。

2. 建议

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

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

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

结构一

### 三级标题

#### 四级标题 A

#### 四级标题 B

#### 四级标题 C

结构二

### 三级标题

**（1）A**

**（2）B**

**（3）C**

二、段落

1.原则

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

（1）段与段之间应该使用空行分隔，保持间隔有助于阅读美观。

（2）段落开头不使用缩进字符填充，与英语文章统一，也便于输入。

（3）段首中心句与段落其他句子的联系，由总到分。

（4）段落长度最好小于等于四行。

（5）文章结尾（完）字宣告文章结束

2. 引用

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

本文转载自 WikiQuote

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

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

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

本文部分图片来自 Wikipedia

三、标点符号

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

（2）注意避免”一逗到底“,合理使用句号分隔段落意思。

（3）补充说明时，使用全角圆括号（（）），括号前后不加空格。

例句：请确认所有的连接（电缆和接插件）均安装牢固。

（4）所有标点符号必须使用中文输入法进行输出。

四、文档体系

记录可以参考的真实范例：

• Redux 手册
• Atom 手册
• 全栈工程师培训材料 - 课堂练习

五、参考链接

• 中文技术文档的写作规范，by 阮一峰

（完）