当前位置: 网站建设 > 网页设计 > 建站经验 >

如何编写优质的API文档

时间:2013-03-02 04:00来源:未知 作者:admin 点击:

标签:如何编写优质的API文档 文档(5)编写(10)质的(4)sample(1)Ap(1)API(2)code(3)如何(201)
sample code in Apples iOS Developer Library 则是这方面做得很好的,它包含了详尽的iOS样例程序,并按主题逐一分类。 --> [网站建设之]如何编写优质的API文档 开发教程:开发教程会更加详细地论述如何使用API,并侧重先容其中的一部门功能。如果能提供可编译运行的源代码,那就再好不外了。 8. 参加人道化的因素 在Parse项目里,我们做到了上述所有三个部分。目前我们正在尽力编制更多的开发教程。 6. 绝不放过任何边界情况 3. 减少点击次数 开发者仇恨点击鼠标
如何编写优质的API文档》文章地址:http://www.tfxk.com/wangyesheji/jianzhanjingyan/0302340J2013.htm

sample code in Apple’s iOS Developer Library 则是这方面做得很好的,它包含了详尽的iOS样例程序,并按主题逐一分类。

--> [网站建设之]如何编写优质的API文档

开发教程:开发教程会更加详细地论述如何使用API,并侧重先容其中的一部门功能。如果能提供可编译运行的源代码,那就再好不外了。

8. 参加人道化的因素

在Parse项目里,我们做到了上述所有三个部分。目前我们正在尽力编制更多的开发教程。

6. 绝不放过任何边界情况

3. 减少点击次数

开发者仇恨点击鼠标,这已经不是什么机密了。千万别把你的文档疏散在数以万计的页面当中。尽量把相干的主题都放到一个页面里。

我们无比同意使用“单页面大指南”的组织情势(链接),这种形式不仅能让用户纵览全局,仅仅通过一个导航栏就能进入他们感兴致的任意主题,另外还有一个利益是:用户在进行搜寻的时候,仅仅搜索当前页面,就能涵盖查找所有的内容。

若要想深刻人心,一个良好的设计文档必不可少。然而,设计一个好文档是需要大批投入能力构成的。然而,这些投入是值得的,因为它的意思和产品本身等同重要。

开发指南:这是介于参考索引和开发教程旁边水平的文档。它就好像是一篇更加具体的参考索引,说明了如何使用各种API。

我见过很多相似的情况,一个项目被轻率地扔到GitHub的页面上,仅仅配有两行的readme解释文件。要知道,真正胜利的API文档是须要用爱来悉心制作的艺术品。在Parse产品项目里,我们就把本人贡献给了这门艺术!

编写技术文档,是令众多开发者望而却步的义务之一。它自身是一件费时费劲才干做好的工作。可是大多数时候,人们却老是想抄抄捷径,这样做的成果往往十分令人遗憾的,由于优质的技巧文档是决议你的名目是否惹人关注的主要因素。无论开源产品或面向开发者的产品,均是如斯。

另外一个此方面优秀的范例是Stripe’s API( 。这个产品的文档包含一个很棒的《hybrid guide and reference》,以及一套开发教程。《GitHub API参考》也经由了良好的设计。

快速指南的目的是让用户用最小的代价学习如何应用你提供的API干一些小事。仅此罢了。一旦用户完成了快速指南,他们就对自己有了信心,并能向更加深入的主题迈进。

MailGun’s API为此做出了良好的模范。它提供了curl,Ruby,Python,Java,C#和PHP等多个版本供开发者抉择。

Tag:文档   优质   编写   如何     文档   优质   编写   如何    

0. 毫不吝惜应用档次

编写良好文档的另一半窍门,是要从产品开发的初始阶段就朝着这个方向努力。不过,这就不是本文探讨的范围了。

万事开头难,开发者学习一套全新的API,不得不从新适应其全新的思维方法,学习代价昂扬。对于这个问题的解决措施是:通过倏地指南来领导开发者。

假如你是一个专门从事面向开发者产品设计的工程师,那么编写完美的技术文档,就跟你为终端用户供给良好用户休会一样症结。

在这个方面的一个优秀典范是ckbone.js documentation,只有你有个鼠标,所有尽在控制。

4. 包含恰当的快速指南

使用API开发运用,所能遭受的最蹩脚的情形,莫过于你发明了一个文档中不提到的过错。如果你碰到这种情况,就象征着你不能确认毕竟是你的程序出了错,仍是你对API的懂得出了错。

参考索引:参考索引应该是一个事无巨细的列表,包含了所有功效函数的繁文缛节。它必需注明所有的数据类型跟函数规格。高等开发者要可能拿着它终日当参考书使用。

那么,什么才是制造优良API文档的要害因素呢?

5. 支撑多种编程语言

至少,这可以保障你的读者不会读着读着就睡从前。

你可以辩论说,我的API本身就是个抽象体, 抽象就是它的特色。然而,当你在教会开发者如何使用的过程中,还是能不抽象就不抽象比拟好。

浏览技术文档单调乏味,天然不像坐过山车那样缓和刺激。不过,你至少能够通过加入一些人性化的因素,或者开开玩笑。给你的例子中的变量其一些好玩儿的名字吧,别总是把函数名称叫什么foo之类的,好让你的读者有面目一新的感到,如何给网页加密

我们生涯在一个多语言的世界。如果可能的话,为你的API提供各种编程语言版本的样例程序,只要的API支持这些语言。多数时候,多语言的工作都是由客户端库来完成的。要晓得,开发者要想把握一套API,分开他们熟习的编程语言,是很难设想的。

7. 提供样例利用

在你的文档中尽可能地举事实中的例子吧。没有哪个开发者会埋怨你举例太多的,如何给网页减肥,让网站提速。实际上,如何给网站导航添加动态分割线,这种做法能明显地缩短开发者理解你产品的时间。对此,我们的网站里甚至给出一个代码样例加以说明。

在学习停止的时候,开发者盼望能看到对于项目产品应用的大抵蓝图。到达这一目标最好的方法,如何确定网站栏目,莫过于提供可运行的样例应用。我发现,应用程序代码是将API运行机理和系统整合融合贯通最好的办法。

论断:

你的设计文档不应当仅仅直白地列出所有的终端函数和其参数。好的文档应当是一整套有机的体系内容,能指援用户通过文档与API进行交互。退一万步说,你至少让你的文档包含以下多少个部分。

因而,参考索引中必须包含每种假设可能造成的边界情况,不管是显示的还是隐式的。花点儿时光在这个上面,相对能起到事半功倍的后果。

实际上,我想阐明的是:对面向开发者的产品来说,其用户体验中最重要的一环并不是什么主页设计、登录进程、或者SDK下载。真正最重要的是产品的API文档!如果没人知道你的产品如何使用,纵使它鬼斧神工,又有何用?

1. 不要在例子中包括形象概念

举个例子,咱们的疾速指南能让用户下载SDK以及在平台上存储一个对象。为此,如何用CSS自定义鼠标显示的形状,我们甚至做了一个按钮,来让用户测试他们是否准确地实现了快捷指南。这能晋升用户的信念,以激励他们学习我们产品其余的局部。


(责任编辑:网站建设)
如何编写优质的API文档相关文章
上一篇:如何给网页加密 下一篇:如何编写优质的需求文档
回到顶部