北京网站建设公司推来客：编写技术文档是许多网站制作开发人员最头疼的工作之一。做好这件事本身就是一件费时费力的工作。但是很多时候，人们总是想抄捷径，而这样做的结果往往是非常令人遗憾的，因为高质量的技术文档是决定你的项目是否受到关注的重要因素。对于开源产品和面向开发人员的产品都是如此。

其实我想说的是，面向开发者的产品，最重要的用户体验不是首页设计、登录流程、SDK下载。最重要的是产品的API文档！如果没有人知道如何使用它，即使它工作出色，你的产品又有什么用呢？

如果您是专门为开发人员设计产品的工程师，那么编写完善的技术文档与为最终用户提供良好的用户体验一样重要。

我见过很多类似的情况，一个项目被粗心地扔到GitHub 页面上，除了两行自述文件外什么都没有。要知道，真正成功的API 文档是一件用爱精心打造的艺术品。在Parse 产品项目中，我们致力于这门艺术！

那么，好的API 文档的关键要素是什么？

1. 千万不要在层次上吝啬

您的设计文档不应只是简单地列出所有终端功能及其参数。一个好的文档应该是一套有机的系统内容，能够引导用户通过文档与API进行交互。退一步说，你至少应该让你的文档包含以下部分。

参考索引：参考索引应该是一个详细的列表，包括所有功能的繁文缛节。它必须注释所有数据类型和函数规范。高级开发人员应该可以整天拿着它，把它当作参考书来使用。

开发指南：这是介于参考索引和开发教程之间的文档。它就像一份更详细的参考资料，解释了如何使用各种API。

开发教程：开发教程会更具体地讲解API的使用方法，重点介绍其部分功能。如果能提供可以编译运行的源码就更好了。

在Parse 项目中，我们执行上述所有三个操作。我们目前正在努力编写更多的开发教程。

另一个很好的例子是Stripe 的API (http://www.stripe.com)。该产品的文档包括一个很棒的《hybrid guide and reference》 和一组开发教程。《GitHub API参考》也设计的不错。

你可以说我的API本身就是一种抽象，抽象就是它的特点。但是，当你在教开发人员如何使用它时，最好不要抽象或不抽象。

在您的文档中尽可能使用真实示例。没有开发人员会抱怨你举了太多的例子。事实上，这样做可以显着减少开发人员了解您的产品所需的时间。我们的网站上什至有一个代码示例来解释这一点。

2. 更少的点击

开发人员讨厌点击鼠标已经不是什么秘密了。切勿将您的文档分散在数万页上。尝试将相关主题放在一页中。

我们非常赞成使用“一页指南”的组织形式（链接）。这种形式不仅可以让用户纵览全局，还可以通过一个导航栏进入任何他们感兴趣的话题。另一个好处是，用户在搜索时，只要搜索当前页面，就可以找到所有的内容。

一个很好的例子就是ckbone.js 文档，只要你有鼠标，一切都在控制之中。

万事开头难。开发人员学习一组新的API，必须重新适应他们的新思维方式。学习成本很高。这个问题的解决方案是通过快速指南来指导开发人员。

快速指南的目的是让用户学习如何使用您提供的API 以最小的努力做一些小事情。就这样。用户完成快速指南后，他们就会对自己充满信心，并可以继续讨论更深入的主题。

例如，我们的快速指南允许用户下载SDK 并将对象存储在平台上。为此，我们甚至制作了一个按钮，让用户测试他们是否正确完成了快速指南。这会增强用户信心并鼓励他们了解我们产品的其他部分。

3.支持多种编程语言

我们生活在一个多语言的世界。如果可能，请以各种编程语言为您的API 提供示例程序，只要您的API 支持这些语言。大多数时候，多语言工作是由客户端库完成的。要知道，开发者要想掌握一套API，离开自己熟悉的编程语言是很难想象的。

MailGun 的API 就是一个很好的例子。它提供了curl、Ruby、Python、Java、C#和PHP多个版本供开发者选择。

4. 永远不要放过任何边缘情况

使用API 开发应用程序最糟糕的事情是发现文档中未提及的错误。如果遇到这种情况，说明你无法确认是你的程序有问题，还是你对API的理解有误。

因此，每

我们专注高端建站，小程序开发、软件系统定制开发、BUG修复、物联网开发、各类API接口对接开发等。十余年开发经验，每一个项目承诺做到满意为止，多一次对比，一定让您多一份收获！