如何写好技术文档？

程序员既要写好代码，又要写好文档。

小樱桃是一个技术团队，我们也跟大多数程序员一样——更喜欢写代码，不喜欢写文档；讨厌别人不写文档，但自己不喜欢写文档。

为什么？因为写文档是非常难的，直到我们读到这篇文章——《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：当你想进一步改进系统、调优、甚至进一步扩展时，就需要完全了解整个系统的原理，读下面两个。

各文档的侧重点对比如下表：

通过使用上述规则，文档作者和读者都很明确什么内容应该放在哪里，以及应该到哪里去找。理解了这些规则，作者就知道如何写、写什么，以及写到哪里。这就是传说中的事半功倍。

推荐大家都好好看看那篇文章，我们也在不断学习，争取我们的文档也能早日进化到理想的样子。