中文技术文档书写指东

0x01 背景前言

我是个记性不太好的人，因此平日里会去写写弄弄把零碎的想法记录下来。之前内容排版上大多都是按照自己的习惯、语言上的常识，在看完阮一峰老师的中文技术文档写作风格指南之后觉得挺有必要去详细了解下技术文档在书写上的一些规范约定，一方面验证自己的习惯是否有问题，另外一方面弥补自己没有注意到的规范细节。

0x02 关于指东

在互联网上中文技术文档写作有指南、指北、指西的，发现还缺少个指东，因此本篇暂且就叫做《中文技术文档写作指东》啦。关于书写规范上，网上已经有不少很好的资料，之所以还想站在前人的肩膀上再来个指东，主要一方面有的规范文档写的很好很全但也会有一些冗余，作为一个手册字典没问题，但不够精简，过多篇幅介绍一些较为常识的语言规范缺少拎出重点；另一方面对于一些仁者见仁的规范还是想结合个人习惯和理解，同时有些规范过于严格了，出版图书写书的确要严格遵循，但日常写写技术博客、文章笔记等我觉得可以稍微自由宽松些，在规范中不失随性即可。

本篇文章在参考各类写作指南的基础上，结合个人的理解进行取长补短，省去一些常识性、不常用的语法规范，提取出较为重要的点汇聚而成。这篇文章不是规范也不是指南，只是一篇建议文档，文虽不成文，仅尽愿者参。

主要参考：
Google、百度相关资料
Github 及 Issues 相关资料
少数派、V2EX、知乎社区相关资料
推特、微博、公共号社交渠道相关资料

0x03 元素排版

1、标题

标题最多不超过四级，下级不重复上级标题名称且每一级递增禁止跳级

✅ 建议：
### 0x01 漏洞描述
### 0x02 漏洞利用

❎ 不建议：
### 0x01 漏洞描述
##### 0x02 漏洞描述

标题的命名建议有一定层级逻辑，标题与标题之间可以有引导介绍内容，例如：

### 0x01 漏洞描述
### 0x02 漏洞影响
### 0x03 漏洞复现
### 0x01 漏洞利用
在利用这个漏洞前，需要xxx
#### 1、获取xxkey值
<内容>
#### 2、组合xx攻击链
<内容>
### 0x05 漏洞修复

标题描述简洁概括，尽量做到如果把文章内容删了，只看标题能够大致知道文章在介绍什么

2、空格

有研究显示，打字的时候不喜欢在中文和英文之间加空格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，而其余三成的人最后只能把遗产留给自己的猫。毕竟爱情跟书写都需要适时地留白。

中文与英文之间需要增加空格

✅ 建议：
Apache Zeppelin 存在未授权的用户访问命令执行接口，导致了任意用户都可以执行恶意命令获取服务器权限。

❎ 不建议：
Apache Zeppelin存在未授权的用户访问命令执行接口，导致了任意用户都可以执行恶意命令获取服务器权限。

⚠️ 特殊情况：
一些专业名词、产品名词按照官方所定义的格式书写，例如「豆瓣FM」。

中文与数字之间需要增加空格

✅ 建议：
影响到了 324 个组件库。

❎ 不建议：
影响到了 324个组件库。
影响到了324个组件库。

数字与单位之间不需要增加空格

✅ 建议：
我家的光纤入户宽带有 10Gbps，SSD 一共有 10TB。

❎ 不建议：
我家的光纤入户宽带有 10 Gbps，SSD 一共有 20 TB。

⚠️ 特殊情况：
度／百分比与数字之间不需要增加空格，例如：今天是 2° 的高温，相比昨天提升了 15% 的温度。

全角标点与其他字符之间不需要加空格

✅ 建议：
刚刚买了一部 iPhone，好开心！

❎ 不建议：
刚刚买了一部 iPhone ，好开心！

引用链接前后之间需要增加空格

✅ 建议：
可以参考 [FreeBuf网络安全行业门户](https://www.freebuf.com/) 网站寻找资料。

❎ 不建议：
可以参考[FreeBuf网络安全行业门户](https://www.freebuf.com/)网站寻找资料。

货币前缀和数字之间不需要空格

✅ 建议：
US$1,234.56

❎ 不建议：
US$ 1,234.56

英文情况下括号的外侧需要保留一个空格

✅ 建议：
RightCapital (a fintech company) is based in Shelton, Connecticut.

❎ 不建议：
RightCapital(a fintech company)is based in Shelton, Connecticut.

3、标点

中英文标点符号全角半角不要混用

✅ 建议：
Zimbra 邮件系统漏洞分析与利用（CVE-2019-9621）

❎ 不建议：
Zimbra 邮件系统漏洞分析与利用(CVE-2019-9621)

⚠️ 特殊情况：
遇到完整的英文整句、特殊名词，其內容中使用半角标点，例如：推荐你阅读《Hackers & Painters: Big Ideas from the Computer Age》，非常的有趣。

简体中文使用直角引号（可选，不混着用即可）

✅ 建议：
「老师，『有条不紊』的『紊』是什么意思？」

❎ 不建议：
“老师，‘有条不紊’的‘紊’是什么意思？”

点号（顿号、逗号、句号等）、结束引号、结束括号等不建议出现在行首

✅ 建议：
自从 Github 宣布推出 CodeQL，越来越多安全人员使用这个项目做代码安全评估工作，截止到此刻，在 Github 上已经有超过3100个Star。

❎ 不建议：
自从 Github 宣布推出 CodeQL，越来越多安全人员使用这个项目做代码安全评估工作
，截止到此刻，在 Github 上已经有超过3100个Star。

引号、括号、书名号不建议出现在行尾

✅ 建议：
Zimbra 邮件系统进行综合利用来达到远程代码执行效果的漏洞（CVE-2019-9621 CVE-2019-9670）。

❎ 不建议：
Zimbra 邮件系统进行综合利用来达到远程代码执行效果的漏洞（
CVE-2019-9621 CVE-2019-9670）。

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

✅ 建议：
关于文件的输出，请参照第 1.3 节（见第 26 页）。

❎ 不建议：
关于文件的输出，请参照第 1.3 节。（见第 26 页）

尽量不重复使用标点，不要万不得已，尽量少用感叹号，平和地表达，才能发出理性的声音
```
比较正式的书写建议遵循，普通的博客技术文档随意即可- -
```

4、数值

“万”、“亿”中文单位可以使用阿拉伯数字，其它中文单位只能使用汉字数字

✅ 建议：
这个代码仓库有 300 万行代码。
这个代码仓库有三百行代码。

❎ 不建议：
这个代码仓库有 3 百万行代码。
这个代码仓库有 3 百行代码。

四位和四位以上的数字应使用逗号作为千位分隔符

✅ 建议：
这个代码仓库有 3,000,000 行代码。

❎ 不建议：
这个代码仓库有 3000000 行代码。
这个代码仓库有 300,0000 行代码。

5、段落

首行不要缩进

每段之前空两格是我们从小学写作文就养成的习惯，也是正式文体的格式要求，其目的是为了区分自然段；但是像我们现在接触的阅读，都是没有固定的格式要求的，如微信公众号、电子文档等，所以大家一般都采用「空出一行」进行自然段与自然段之间的区分，这种写作方式非常省事，而且很整齐。所以只要没有明确的格式要求，写作的排版无须首行缩进。

克制地使用样式工具

样式工具的使用可以增加文章的可读性，但是过度使用则会造成排版混乱，不建议过度使用「加粗」、「斜体」等样式工具

段落之间使用一个空行隔开，例如：

### 0x01 漏洞描述
<内容>

---

### 0x02 漏洞利用
<内容>

6、引用

有使用外站引用内容的，务必在最后注明来源及链接，同时如果是图片引用外站，建议直接在图片下方注明来源
若文章为全文翻译，必须在文中注明原作者及原文链接地址

7、名词

少使用不地道的缩写

✅ 建议：
我们需要一位熟悉 JavaScript、HTML5，至少理解一种框架（如 Backbone.js、AngularJS、React 等）的前端开发者。

❎ 不建议：
我们需要一位熟悉 Js、h5，至少理解一种框架（如 backbone、angular、RJS 等）的 FED。

专有名词使用正确的大小写

✅ 建议：
GitHub、iOS、iPhone 6s、MacBook Pro

❎ 不建议：
github、IOS、iphone 6s、macbook pro

非专有名词，英文名词首字母统一大小写

✅ 建议：
Google、Android、Facebook
google、android、facebook

❎ 不建议：
Google、android、Facebook

对于中文读者熟知的产品名称只需用中文名称，不熟知中文译名后括号补充英文，例如：
```
熟知的：苹果、华为；不熟知的：威睿 (VMware)。
```

8、命名

文件命名尽量少出现空格，包含英文建议优先都使用小写字母或统一用大写开头，若出现多个英文单词时，建议使用短划线“-”分隔而非“_”

✅ 建议：
基于vulnerability-databases的建设.md
基于Vulnerability-Databases的建设.md

❎ 不建议：
基于Vulnerability databases的建设.md
基于Vulnerability_Databases的建设.md

⚠️ 特殊情况：
为了醒目某些说明文件的文件名，可以使用大写字母，比如README、LICENSE。

9、结构

有头有尾，循序渐进有逻辑层次结构风格，例如：

文章标题

一两句话介绍本文的内容。

效果

大致介绍 demo 的用法，并展示效果。

原理

逐步介绍原理。

总结

做一个简单的总结。

参考与致谢

参考链接1
参考链接1

总 - 分 - 总的结构风格，例如：

总：
即文首先告诉读者会读到什么，如果读者不感兴趣的话可以省下来读一篇文章的时间，而如果感兴趣的话正好是个好引子。

分：
即分散表达需要表达的观点，比如在本文中，即三个部分：关于内容、关于标点和关于行文的三块建议。

总：
最后总结文章，你要假设读者并没有时间详读全文，但这里的总结可以让读者能在 10 秒内仍然知道你在这篇文章里表达了什么

乌云知识库（曾经某知名安全站点） + 个人调整风格，例如：

尽量对所研究的内容做到闭环，例如研究某个漏洞可以先从背景起因说起为什么研究这个漏洞，模拟自己是发现者猜测漏洞是如何被发现的，为什么能找到这个漏洞点，然后进行复现分析、自动化利用以及修复防御等，对一个漏洞从发现到利用防御进行一个闭环。排版样式下沿用乌云知识库的16进制标题形式。

0x01 起因前言

——————

0x02 漏洞描述
...
0x08 最后总结
0x09 参考引用

Github项目 README 或者 Wiki，有个层级的总览目录然后串出结构，例如：
```
https://github.com/iina/iina/wiki
```

0x04 文笔风格

1、简洁直白

尽量使用简洁直白的语言，少一些冗余的形容词以及少用"的"

✅ 建议：
我们认为人人生而平等。

❎ 不建议：
我们认为以下真理是不言而喻的：人人生而平等。

避免使用长句

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

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

尽量用主动语态，不要用被动语态，一般情况下，主动语态比被动语态更有力
```
✅ 建议：
假如尚未安装这个软件

❎ 不建议：
假如此软件尚未被安装
```

尽量使用简单句和并列句，避免使用复合句

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

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

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

✅ 建议：
请确认装置的电源已关闭。

❎ 不建议：
请确认没有接通装置的电源。

避免使用双重否定句

✅ 建议：
用户必须拥有删除权限，才能删除此文件。

❎ 不建议：
没有删除权限的用户，不能删除此文件。

2、用词恰当

论点要有论据支持，避免只说理不举例
少出现“最佳”、“最好”、“最著名”、“最新技术”、“最高水平”、“最先进水平”等具有强烈评价色彩的词语
表示变化程度要严谨不要含糊不清，例如：增加到过去的两倍

3、轻松诙谐

适当可以使用一些表情包，增强文章整体的轻松感
介绍技术时候尽可能诙谐方式深入浅出描述出来，多举一些生活中通用的例子进行解释，专业的技术用简单的方式描述既对读者友好，也是自己对技术深入的理解吸收

4、少些黑话

避免过多遣词造句以及一些互联网黑话、过于正式的书面语等，直接直白的口语化，怎么舒服怎么来，在规范之上，正式之下的风格。

5、换位思考

写技术文章时候大多是这项技术自己已经会了，但在写的时候尽可能去换位思考，考虑之前自己空杯状态会思考哪些问题等，可以把这些问题自己的思路给写出来，对一些其他人研究这项技术来说更有好的引导。

0x05 文笔技巧

1、确定文章大纲逻辑

在动笔之前先有一个大致的文章思路，列出大纲以及研究过程中重要的点，有时候写一篇文章可能需要好几天以及查找资料的时候也会出现新的思路，因此提前列出一些大纲要点能够避免忘记。

2、及时记录闪现灵感

写文章突然写会比较棘手不知道写哪些，但平时带着想下然后这些闪现的灵感想法及时记录下，这样在写的时候只要看平时记的一些关键字回忆下即可快速的串起来，能够写的更加流畅些。

3、日常收藏归纳整理

平时碎片化的知识收藏与整理归档很重要，既要收藏，也要定期对这些资料进行归档吸收，让自己的大脑处在一个目录的状态。如果列大纲，记灵感如果是术的话，长期收藏归档学习就是道了，我是一个碎片收藏归纳的获益者，真切感受到长期积累的学习会让思维方式迁移魔化中有一些提高，这部分能够讲的东西会比较多，可以今后单独写一篇分享。