如何编写优质的 API 文档

jopen 12年前
     编写技术文档,是令众多开发者望而生畏的任务之一。它本身是一件费时费力才能做好的工作。可是大多数时候,人们却总是想抄抄捷径,这样做的结果往往非常令 人遗憾的,因为优质的技术文档是决定你的项目是否引人关注的重要因素。无论开源产品或面向开发者的产品,均是如此。 实际上,我想说明的是:对于面向开发者的产品来说,其用户体验中最重要的一环并不是什么主页设计、登录过程、或者SDK下载。真正最重要的是产品的API 文档!如果没人知道你的产品如何使用,纵使它巧夺天工,又有何用?    <br />    <br /> 如果你是一个专门从事面向开发者产品设计的工程师,那么编写完善的技术文档,就跟你为终端用户提供良好用户体验一样关键。(API 设计是很聪明的投资,你得到的回报是忠实的开发人员。详见:《    <a href="/misc/goto?guid=4958319693759906993">为什么“开发人员友好性”是API设计的核心</a>》。)    <br />    <br /> 我见过许多类似的情况,一个项目被草率地扔到GitHub的页面上,仅仅配有两行的readme说明文件。要知道,真正成功的API文档是需要用爱来悉心制作的艺术品。在Parse产品项目里,我们就把自己奉献给了这门艺术!    <br />    <br /> 那么,什么才是制作优秀API文档的关键因素呢?    <br />      <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">0. 绝不吝惜使用层次</strong>    <br /> 你的设计文档不应当仅仅直白地列出所有的终端函数和其参数。好的文档应该是一整套有机的系统内容,能指引用户通过文档与API进行交互。退一万步说,你至少让你的文档包含以下几个部分。    <br /> 参考索引:参考索引应当是一个事无巨细的列表,包含了所有功能函数的繁文缛节。它必须注明所有的数据类型和函数规格。高级开发者要能够拿着它整天当参考书使用。    <br /> 开发指南:这是介于参考索引和开发教程中间程度的文档。它就仿佛是一篇更加详细的参考索引,阐明了如何使用各种API。    <br /> 开发教程:开发教程会更加具体地阐述如何使用API,并着重介绍其中的一部分功能。如果能提供可编译运行的源代码,那就再好不过了。    <br /> 在Parse项目里,我们做到了上述所有三个部分。目前我们正在努力编制更多的开发教程。    <br /> 另外一个此方面优秀的范例是Stripe’s API(http://www.stripe.com) 。这个产品的文档包括一个很棒的《hybrid guide and reference》,以及一套开发教程。《GitHub API参考》也经过了良好的设计。    <br />      <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">1. 不要在例子中包含抽象概念</strong>    <br /> 你可以争辩说,我的API本身就是个抽象体, 抽象就是它的特点。然而,当你在教会开发者如何使用的过程中,还是能不抽象就不抽象比较好。    <br /> 在你的文档中尽可能地举现实中的例子吧。没有哪个开发者会抱怨你举例太多的。实际上,这种做法能显著地缩短开发者理解你产品的时间。对此,我们的网站里甚至给出一个代码样例加以解释。    <br />      <br />    <img style="border-bottom:#d4d4d4 1px solid;border-left:#d4d4d4 1px solid;padding-bottom:5px;background-color:#ffffff;margin:5px 0px 0px;padding-left:5px;width:546px;padding-right:5px;height:330px;border-top:#d4d4d4 1px solid;border-right:#d4d4d4 1px solid;padding-top:5px;" class="size-full wp-image-10512" title="如何编写优质的API文档" alt="如何编写优质的 API 文档" src="https://simg.open-open.com/show/11c45a200b83672d251f89307c244280.gif" />    <br />    <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">3. 减少点击次数</strong>    <br /> 开发者痛恨点击鼠标,这已经不是什么秘密了。千万别把你的文档分散在数以万计的页面当中。尽量把相关的主题都放到一个页面里。    <br /> 我们非常赞成使用“单页面大指南”的组织形式(    <a href="/misc/goto?guid=4958332388075184943">链接</a>),这种形式不仅能让用户纵览全局,仅仅通过一个导航栏就能进入他们感兴趣的任意主题,另外还有一个好处是:用户在进行搜索的时候,仅仅搜索当前页面,就能涵盖查找所有的内容。    <br /> 在这个方面的一个优秀范例是    <a href="/misc/goto?guid=4958319783243894395">ckbone.js documentation</a>,只要你有个鼠标,一切尽在掌握。    <br />      <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">4. 包含适当的快速指南</strong>    <br /> 万事开头难,开发者/程序员学习一套全新的API,不得不重新适应其全新的思维方式,学习代价高昂。对于这个问题的解决办法是:通过快速指南来引导开发者。    <br /> 快速指南的目的是让用户用最小的代价学习如何利用你提供的API干一些小事。仅此而已。一旦用户完成了快速指南,他们就对自己有了信心,并能向更加深入的主题迈进。    <br /> 举个例子,我们的快速指南能让用户下载SDK以及在平台上存储一个对象。为此,我们甚至做了一个按钮,来让用户测试他们是否正确地完成了快速指南。这能提升用户的信心,以鼓励他们学习我们产品其他的部分。    <br />      <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">5. 支持多种编程语言</strong>    <br /> 我们生活在一个多语言的世界。如果可能的话,为你的API提供各种编程语言版本的样例程序,只要的API支持这些语言。多数时候,多语言的工作都是由客户端库来完成的。要知道,开发者要想掌握一套API,离开他们熟悉的编程语言,是很难想象的。    <br />    <a href="/misc/goto?guid=4958332389629699604">MailGun’s API</a>为此做出了良好的榜样。它提供了curl,Ruby,Python,Java,C#和PHP等多个版本供开发者选择。    <br />      <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">6. 绝不放过任何边界情况</strong>    <br /> 使用API开发应用,所能遭遇的最糟糕的情况,莫过于你发现了一个文档中没有提到的错误。如果你遇到这种情况,就意味着你不能确认究竟是你的程序出了错,还是你对API的理解出了错。    <br /> 因此,参考索引中必须包含每种假设可能造成的边界情况,不论是显示的还是隐式的。花点儿时间在这个上面,绝对能起到事半功倍的效果。    <br />      <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">7. 提供样例应用</strong>    <br /> 在学习结束的时候,开发者希望能看到关于项目产品应用的大致蓝图。达到这一目的最好的办法,莫过于提供可运行的样例应用。我发现,应用程序代码是将API运行机理和系统整合融会贯通最好的办法。    <br />    <a href="http://developer.apple.com/library/ios/navigation/#section=Resource%20Types&amp;topic=Sample%20Code">sample code in Apple’s iOS Developer Library</a> 则是这方面做得很好的,它包含了详尽的iOS样例程序,并按主题一一分类。    <br />      <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">8. 加入人性化的因素</strong>    <br /> 阅读技术文档枯燥乏味,自然不像坐过山车那样紧张刺激。不过,你至少可以通过加入一些人性化的因素,或者开开玩笑。给你的例子中的变量其一些好玩儿的名字吧,别老是把函数名称叫什么foo之类的,好让你的读者有焕然一新的感觉。    <br /> 至少,这可以保证你的读者不会读着读着就睡过去。    <br />      <br />    <strong style="padding-bottom:0px;margin:0px;padding-left:0px;padding-right:0px;padding-top:0px;">结论:</strong>    <br /> 若要想深入人心,一个良好的设计文档必不可少。然而,设计一个好文档是需要大量投入才能形成的。但是,这些投入是值得的,因为它的意义和产品本身同等重要。    <br /> 编写良好文档的另一半诀窍,是要从产品开发的初始阶段就朝着这个方向努力。不过,这就不是本文讨论的范畴了。    <br />      <br /> 英文原文:    <a href="/misc/goto?guid=4958332391235232710">James Yu</a>    编译:    <a href="/misc/goto?guid=4958185140659301754">伯乐</a>在线