编写优质的API文档的方法，怎么进行API文档的编写，API文档优质的编写方法

编写技术文档，API文档优质的编写方法，是令众多开发者望而生畏的任务之一。它本身是一件费时费力才能做好的工作。可是大多数时候，人们却总是想抄抄捷径，这样做的结果往往非常令人遗憾的，因为优质的技术文档是决定你的项目是否引人关注的重要因素。无论开源产品或面向开发者的产品，均是如此。

使用API开发应用，所能遭遇的最糟糕的情况，莫过于你发现了一个文档中没有提到的错误。《GitHub API参考》也经由了良好的设计。

我们糊口在一个多语言的世界。

1. 支持多种编程语言

举个例子，我们的快速指南能让用户下载SDK以及在平台上存储一个对象。

2. 减少点击次数

在你的文档中尽可能地举现实中的例子吧。

参考索引：参考索引应当是一个事无巨细的列表，包含了所有功能函数的繁文缛节。

在学习结束的时候，开发者但愿能看到关于项目产品应用的大致蓝图。它必需注明所有的数据类型和函数规格。我发现，应用程序代码是将API运行机理和系统整合融会贯通最好的办法。

3. 提供样例应用

因此，参考索引中必需包含每种假设可能造成的边界情况，不论是显示的仍是隐式的。然而，当你在教会开发者如何使用的过程中，仍是能不抽象就不抽象比较好。

你的设计文档不应当仅仅直白地列出所有的终端函数和其参数。它就仿佛是一篇更加具体的参考索引，阐明了如何使用各种API。目前我们正在努力编制更多的开发教程。假如能提供可编译运行的源代码，那就再好不外了。

4. 毫不放过任何边界情况

MailGun’s API为此做出了良好的榜样。
阅读技术文档枯燥乏味，天然不像坐过山车那样紧张刺激。仅此而已。

在Parse项目里，我们做到了上述所有三个部门。高级开发者要能够拿着它整天当参考书使用。对此，我们的网站里甚至给出一个代码样例加以解释。

5. 加入人道化的因素

sample code in Apple’s iOS Developer Library 则是这方面做得很好的，它包含了详尽的iOS样例程序，并按主题逐一分类。给你的例子中的变量其一些好玩儿的名字吧，别总是把函数名称叫什么foo之类的，好让你的读者有焕然一新的感觉。

快速指南的目的是让用户用最小的代价学习如何利用你提供的API干一些小事。

万事开头难，开发者学习一套全新的API，不得不重新适应其全新的思维方式，学习代价高昂。
你可以争辩说，我的API本身就是个抽象体， 抽象就是它的特点。它提供了curl，Ruby，Python，Java，C#和PHP等多个版本供开发者选择。要知道，真正成功的API文档是需要用爱来悉心制作的艺术品。

至少，这可以保证你的读者不会读着读着就睡过去。API文档优质的编写方法，实际上，这种做法能明显地缩短开发者理解你产品的时间。千万别把你的文档分散在数以万计的页面当中。为此，我们甚至做了一个按钮，来让用户测试他们是否准确地完成了快速指南。真正最重要的是产品的API文档！假如没人知道你的产品如何使用，纵使它巧夺天工，又有何用？

这能晋升用户的决心信念，以鼓励他们学习我们产品其他的部门。达到这一目的最好的办法，莫过于提供可运行的样例应用。多数时候，多语言的工作都是由客户端库来完成的。要知道，开发者要想把握一套API，离开他们认识的编程语言，是很难想象的。尽量把相关的主题都放到一个页面里。不外，你至少可以通过加入一些人道化的因素，或者开开玩笑。对于这个题目的解决办法是：通过快速指南来引导开发者。一旦用户完成了快速指南，他们就对自己有了决心信念，并能向更加深入的主题迈进。在Parse产品项目里，我们就把自己奉献给了这门艺术！

假如你是一个专门从事面向开发者产品设计的工程师，那么编写完善的技术文档，就跟你为终端用户提供良好用户体验一样枢纽。假如你碰到这种情况，就意味着你不能确认毕竟是你的程序出了错，仍是你对API的理解出了错。花点儿时间在这个上面，绝对能起到事半功倍的效果。

开发教程：开发教程会更加详细地阐述如何使用API，并着重先容其中的一部门功能。

实际上，我想说明的是：对于面向开发者的产品来说，其用户体验中最重要的一环并不是什么主页设计、登录过程、或者SDK下载。这个产品的文档包括一个很棒的《hybrid guide and reference》，以及一套开发教程。

开发者痛恨点击鼠标，这已经不是什么秘密了。

6. 包含适当的快速指南

在这个方面的一个优秀范例是ckbone.js documentation，只要你有个鼠标，一切尽在把握。没有哪个开发者会诉苦你举例太多的。好的文档应该是一整套有机的系统内容，能指引用户通过文档与API进行交互。退一万步说，你至少让你的文档包含以下几个部门。

7. 不要在例子中包含抽象概念

另外一个此方面优秀的范例是Stripe’s API（http://www.stripe.com） 。

开发指南：这是介于参考索引和开发教程中间程度的文档。

8. 毫不吝惜使用层次

那么，什么才是制作优秀API文档的枢纽因素呢？

我见过很多类似的情况，一个项目被草率地扔到GitHub的页面上，仅仅配有两行的readme说明文件。

我们非常赞成使用“单页面大指南”的组织形式（链接），这种形式不仅能让用户纵览全局，仅仅通过一个导航栏就能进入他们感爱好的任意主题，另外还有一个好处是：用户在进行搜索的时候，仅仅搜索当前页面，就能涵盖查找所有的内容。假如可能的话，为你的API提供各种编程语言版本的样例程序，只要的API支持这些语言。

新闻标题：编写优质的API文档的方法，怎么进行API文档的编写，API文档优质的编写方法
文章网址：/news9/166209.html

成都网站建设公司_创新互联，为您提供域名注册、网页设计公司、手机网站建设、动态网站、建站公司、定制开发

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 创新互联