编写技术文档，是令众多开发者望而生畏的任务之一。它本身是一件费时费力才能做好的工作。可是大多数时候，人们却总是想抄抄捷径，这样做的结果往往非常令人遗憾的，因为优质的技术文档是决定你的项目是否引人关注的重要因素。无论开源产品或面向开发者的产品，均是如此。
实际上，我想说明的是：对于面向开发者的产品来说，其用户体验中最重要的一环并不是什么主页设计、登录过程、或者SDK下载。真正最重要的是产品的API文档！如果没人知道你的产品如何使用，纵使它巧夺天工，又有何用？
如果你是一个专门从事面向开发者产品设计的工程师，那么编写完善的技术文档，就跟你为终端用户提供良好用户体验一样关键。
我见过许多类似的情况，一个项目被草率地扔到GitHub的页面上，仅仅配有两行的readme说明文件。要知道，真正成功的API文档是需要用爱来悉心制作的艺术品。在Parse产品项目里，我们就把自己奉献给了这门艺术！
那么，什么才是制作优秀API文档的关键因素呢？
0. 绝不吝惜使用层次
你的设计文档不应当仅仅直白地列出所有的终端函数和其参数。好的文档应该是一整套有机的系统内容，能指引用户通过文档与API进行交互。退一万步说，你至少让你的文档包含以下几个部分。
参考索引：参考索引应当是一个事无巨细的列表，包含了所有功能函数的繁文缛节。它必须注明所有的数据类型和函数规格。高级开发者要能够拿着它整天当参考书使用。
开发指南：这是介于参考索引和开发教程中间程度的文档。它就仿佛是一篇更加详细的参考索引，阐明了如何使用各种API。
开发教程：开发教程会更加具体地阐述如何使用API，并着重介绍其中的一部分功能。如果能提供可编译运行的源代码，那就再好不过了。
在Parse项目里，我们做到了上述所有三个部分。目前我们正在努力编制更多的开发教程。
另外一个此方面优秀的范例是Stripe’s API（http://www.stripe.com） 。这个产品的文档包括一个很棒的《hybrid guide and reference》，以及一套开发教程。《GitHub API参考》也经过了良好的设计。
1. 不要在例子中包含抽象概念
你可以争辩说，我的API本身就是个抽象体， 抽象就是它的特点。然而，当你在教会开发者如何使用的过程中，还是能不抽象就不抽象比较好。
在你的文档中尽可能地举现实中的例子吧。没有哪个开发者会抱怨你举例太多的。实际上，这种做法能显著地缩短开发者理解你产品的时间。对此，我们的网站里甚至给出一个代码样例加以解释。