XSwitch通信百科
如何写好技术文档？
程序员既要写好代码，又要写好文档。
小樱桃是一个技术团队，我们也跟大多数程序员一样——更喜欢写代码，不喜欢写文档；讨厌别人不写文档，但自己不喜欢写文档。
为什么？因为写文档是非常难的，直到我们读到这篇文章——《The documentation system》。
The Grand Unified Theory of Documentation —— David Laing
写好文档的终极秘密是——首先要理解，文档并不是一个东西，而是四个。看图：
其实这也不算是秘密，也不应该是秘密。一个好的文档应该包含四个部分：Tutorial、How-To 指南、技术参考以及解释。每一部分都是不同的写作模式，有不同的侧重点。人们在阅读技术文档时，在不同的时间需要读不同的文档。所有的文档都要有，而且不要交叉。
从上图可以看出，图中有四个象限，如果你没有时间读四个文档，你可以先两个两个的读，如：
- Most userful when we're studing：当你在调研、学习时，应该读左边两个。
- Practical steps：当你想实际练习一下，或先做一个简单的演示系统时，读上面两个。
- Most useful when we're working：当你继续工作，把系统做得更实用、更完美时，读右边两个。
- Theoretical knowledge：当你想进一步改进系统、调优、甚至进一步扩展时，就需要完全了解整个系统的原理，读下面两个。
各文档的侧重点对比如下表：
| . | Tutorials | How-to guides | Reference | Explanation |
|---|---|---|---|---|
| 面向对象 | 初学者 | 有目的的要做成一件事的人 | 获取信息的人 | 理解整个系统的人 |
| 必须做到 | 让新手能上手 | 展示如何解决一个特定问题 | 描述相关参数 | 解释为什么会这样 |
| 形式 | 一节课 | 一系列步骤 | 纯描述 | 深度解读 |
| 举例 | 教一个小孩如何做饭 | 一份菜谱 | 一本做饭的百科全书 | 一篇介绍烹饪发展史的文章 |
通过使用上述规则，文档作者和读者都很明确什么内容应该放在哪里，以及应该到哪里去找。理解了这些规则，作者就知道如何写、写什么，以及写到哪里。这就是传说中的事半功倍。
上面虽然说的是大文档，但我觉得对于小文档也同样适用。也就是说，当你在写一篇文章（文章比较短没必要分成一系列文档）的时候，也要有意识的把文章分成几个部分，前面的部分概括一下该文档要讲什么，在开始的时候也讲几个简单的入门例子，后面再写一些详细的步骤之类的。这样读者就可以快速了解文档的内容，以及从文档中能学到什么。
推荐大家都好好看看那篇文章，我们也在不断学习，争取我们的文档也能早日进化到理想的样子。