北京网站成立公司尚品中国：编写技能文档，是令浩瀚网站制作开辟者望而却步的使命之一。它自己是一件费时辛苦才气做好的工作。但是大大都时辰，人们却总是想抄抄捷径，如许做的后果常常极度使人遗憾的，由于优良的技能文档是决意你的项目是不是引人存眷的重要身分。不管开源产物或面向开辟者的产物，均是如斯。
实际上，我想注释的是：关于面向开辟者的产物来讲，其用户体验中最重要的一环其实不是甚么主页计划、登录进程、或许SDK下载。真正最重要的是产物的API文档！假定没人晓得你的产物若何应用，纵使它鬼斧神工，又有何用？
假定你是一个特地处置面向开辟者产物计划的工程师，那末编写美满的技能文档，就跟你为终端用户供应优越用户体验一样要害。
我见过很多类似的情况，一个项目被轻率地扔到GitHub的页面上，仅仅配有两行的readme注释文件。要晓得，真正胜利的API文档是需要用爱来悉心制作的艺术品。在Parse产物项目里，我们就把自己贡献给了这门艺术！
那末，甚么才是制作优良API文档的要害身分呢？
1. 毫不怜惜应用条理
你的计划文档不应该仅仅直白地列出统统的终端函数和其参数。好的文档应该是一整套无机的体系内容，能指援用户经由过程文档与API停止交互。退一万步说，你最少让你的文档包括以下几个部分。
参考索引：参考索引应该是一个事无巨细的列表，包括了统统功效函数的繁文缛节。它必需说明统统的数据范例和函数规格。高等开辟者要可以或许拿着它成天当参考书应用。
开辟指南：这是介于参考索引和开辟教程中央程度的文档。它就好像是一篇更加具体的参考索引，说明晰若何应用各类API。
开辟教程：开辟教程会更加具体地论述若何应用API，并侧重先容个中的一部分功效。假定能供应可编译运转的源代码，那就再好不外了。
在Parse项目里，我们做到了上述统统三个部分。今朝我们正在尽力体例更多的开辟教程。
此外一个此方面优良的范例是Stripe’s API(http://www.stripe.com) 。这个产物的文档包罗一个很棒的《hybrid guide and reference》，和一套开辟教程。《GitHub API参考》也经由了优越的计划。
你可以或许辩论说，我的API自己就是个笼统体， 笼统就是它的特点。但是，当你在教会开辟者若何应用的进程中，照旧能不笼统就不笼统对照好。
在你的文档中尽大要地举实际中的例子吧。没有哪一个开辟者会诉苦你举例太多的。实际上，这类做法能明显地延长开辟者理解你产物的时候。对此，我们的网站里乃至给出一个代码样例加以注释。
2. 削减点击次数
开辟者悔恨点击鼠标，这已不是甚么诡秘了。万万别把你的文档疏散在数以万计的页面傍边。尽量把相干的主题都放到一个页面里。
我们极度赞成应用“单页面大指南”的组织方式(链接)，这类方式不仅能让用户纵览全局，仅仅经由过程一个导航栏就能进入他们感爱好的恣意主题，此外另有一个优点是：用户在停止搜刮的时辰，仅仅搜刮以后页面，就能涵盖查找统统的内容。
在这个方面的一个优良范例是ckbone.js documentation，只需你有个鼠标，统统尽在掌握。
万事开头难，开辟者进修一套全新的API，不能不从新顺应其全新的思想体例，进修价格昂扬。关于这个成绩的处置办法是：经由过程疾速指南来向导开辟者。
疾速指南的目的是让用户用最小的价格进修若何操纵你供应的API干一些小事。仅此罢了。一旦用户完成了疾速指南，他们就对自己有了决心，并能向更加深化的主题迈进。
举个例子，我们的疾速指南能让用户下载SDK和在平台上存储一个工具。为此，我们乃至做了一个按钮，来让用户测试他们是不是正确地完成了疾速指南。这能提拔用户的决心，
营销型SEO优化，以勉励他们进修我们产物其他的部分。
3. 支撑多种编程说话
我们生涯在一个多说话的天下。假定大要的话，为你的API供应各类编程说话版本的样例挨次，只需的API支撑这些说话。大都时辰，多说话的工作都是由客户端库来完成的。要晓得，开辟者要想掌握一套API，离开他们认识的编程说话，是很难设想的。
MailGun’s API为此做出了优越的典范。它供应了curl，Ruby，Python，Java，C#和PHP等多个版本供开辟者遴选。
4. 毫不放过任何界限情况
应用API开辟操纵，所能遭遇的最蹩脚的情况，莫过于你创造晰一个文档中没有提到的毛病。假定你碰着这类情况，就意味着你不克不及确认究竟是你的挨次出了错，照旧你对API的理解出了错。
是以，参考索引中必需包括每种假定大要形成的界限情况，岂论,是表现的照旧隐式的。花点儿时候在这个上面，相对能起到事半功倍的后果。
在进修竣事的时辰，开辟者进展能看到关于项目产物操纵的大抵蓝图。到达这一目的最好的办法，莫过于供应可运转的样例操纵。我创造，操纵挨次代码是将API运转机理和体系整合举一反三最好的办法。
sample code in Apple’s iOS Developer Library 则是这方面做得很好的，它包括了详实的iOS样例挨次，并按主题逐一分类。
5. 插足人道化的身分
浏览技能文档单调有趣，天然不像坐过山车那样重要安慰。不外，你最少可以或许经由过程插足一些人道化的身分，或许开开玩笑。给你的例子中的变量其一些好玩儿的名字吧，别总是把函数称号叫甚么foo之类的，好让你的读者有面目一新的感受。
最少，这可以或许包管你的读者不会读着读着就睡过去。
本文宣布于北京网站制作公司尚品中国http://www.sino-web.net/