怎么写好技术文档

写在前面：
我也没想到我的第一篇正式的技术博客会是关于怎么写文档的。因为最近在实习，刚好，师姐让我写一篇文档。然后，作为小白的我当然第一版写的乱七八糟。后来，师姐给了一个方向。然后，我模模糊糊的get到了什么。后来，我就开始去查，然后阅读了很多人的博客and书籍。花了大概几个小时的时间去想明白到底该怎么写文档。其实这些点并没有难度上的要求，难得是当你准备写文档的时候，这几个准则始终记在心里。

第一点：这是很多人的共识，先明确你的写作对象。

我记得我第一份实习的时候，我召开了一个代码的review会议。然后，我们老大对我的代码提的要求在我看来很奇怪。后来，我和带我的师兄聊了一下。他说，因为我们上次聊这个问题的时候进展到那里。所以，他对于这个事情的记忆一直停留在那个节点。所以，后面我们的讨论他都不知道，所以说的和我现在的东西对不上也就可以理解了。
你看，即使是同一个部门和你的业务密切相关的人，老大和天天带你的师兄都是两个完全不同的读者。所以，如果你不明确你的读者，你的文档的可读性就完全没法保证。因为可读性不是由你来评判的，而是由你的读者来评判。

第二点：确定写作目标

你写这篇文章是为了向你的读者传达什么信息。这是你要明确的目标。如果写作目标都不明确，那你的文档即使写出来，因为没有重点，也可能被人弃之不读。如果你不想出现这种情况，那还是最好在动笔前，先把写作目的写在开头，等到文章全部写完之后，对着写作目标再看一遍文章。如果没问题，删掉写作目的，文章完成。

第三点：确定文章结构

我知道搜到这篇文章的人大都是因为：我没有思路，我不知道该怎么写，大脑一片空白。以下两种方式或许对于你的行文有所帮助

1.总分（总）

我知道这是小学作文里都会用的套路。但是，it works。对了，比较专业一点的说法是叫做金字塔原理。
金字塔原理：
中心思想1
1. 支撑观点
2. 支撑观点
3. 支撑观点
中心思想2
1. 支撑观点
2. 支撑观点
3. 支撑观点
中心思想3
1. 支撑观点
2. 支撑观点
3. 支撑观点
参考前面的写作目的，你大可以把你的结论放在文章的开头，然后，从几个方面找些论点以及证据来支撑你的结论，最终以期说服你的同事，主管，业务伙伴。

2.MECE原则

MECE原则其实就两条：
完整性：保证一个项目被分解的完整，没有漏掉某些项目。
独立性：强调每项工作之间要独立，每项工作之间不能有交叉。
但是，把一个具体的问题按照这两个原则进行分割并不容易，下面我举一个我的例子，希望对读者有所帮助。
eg：
在写文章之初，我也是大脑一片空白，直到一个公式突然出现在我的脑海里，结合上MECE原则，然后整个文章的结构就都有了。
这个公式就是：
程序=算法+数据结构
没错就是绝大多数计算机类的教科书第一章甚至引言都会出现的公式！
所以，我的idea是，既然我要针对一个程序进行说明，那么我就拆分成，对算法的说明以及对数据结构的说明。用了哪些数据结构，分别是怎么实现的。用了哪些算法，分别是怎么实现的。按照这个思路，我很快列出了，我要说明的数据结构以及算法。然后很快写出了文档。
最后，师姐给的回复是：结构没问题，个别语句不清晰。就这样作为一个从没学过怎么写技术文档的我，成功的写出了一篇技术文档~
写在最后：在查资料的时候，发现外国的大学已经有专门的技术文档专业了。而我国类似的课程可能只在部分顶尖大学刚刚开始。这从一个侧面说明，追赶的路上道阻且长，与诸君共勉~