教你写好开发者文档的 8 个最佳案例

你刚刚收到来自一位愤怒的开发者的电子邮件。你的文档有问题，开发人员花了几个小时才弄明白。现在轮到你更新文档，并找出如何在将来避免这些问题。 但是要怎么做呢？

创建出色的文档是很难的。致力于此通常意味着忽略了你工作的另一部分 - 而那段时间可能与开发工作一样有价值。每周几个小时改善文档可能会产生组合效应。开发人员陷入此种困境的频率会降低，请求支持的次数将会减少，并且老天保佑的话，愤怒式电子邮件也将减少。事实上，当你有很好的开发文档时，你甚至可能会经常收到快乐热情的电子邮件。

这篇文章展示了8个很不错的开发者文档例子，其撰写投入的时间为开发的团队带来极大的收益。 那么来找找您喜欢的文档功能，并在自己的文档中使用它们，使您自己的文档更有价值。

开发者主页


文档首页面向三类用户。 Heroku开发中心通过多种方式来帮助这三类用户找到他们需要的信息。 首先，在首页导航栏下面，用30号的字体来说明该网站的目的：学习如何在Heroku上创建，开发，管理你的应用程序。在这下面，列举了Heroku支持的8种开发语言。因此浏览首页后，开发人员立刻就能知道Heroku提供了什么，以及这里是否有他们需要的东西。

同时，主导航栏和副导航栏也帮助新开发人员使用该网站————解决问题、开始使用、或了解更多关于Heraku的信息。如果主页上没有吸引开发者的内容，或许这些详细列表里有他们需要的东西。如果都没有，那么就可以收集开发者的反馈信息，了解他们最需要什么，确保首页就能提供他们最需要的信息。

当开发者查看你的文档主页时，他们可能是：

1. 想知道你提供了什么
2. 想要开始进行开发
3. 遇到困难想寻求帮助

入门指南页面


快速入门指南在向开发人员介绍新技术方面有着重要作用，它也是使你的API广泛传播的最重要因素。 并且作为给开发人员的第一印象，制作入门指南需要格外用心。

GitHub 是一个具有很多高级用户的工具，尽管如此，用户的高知识水平也不该是制作复杂的入门指南的借口。 其入门指南超过 2,000 个字，这不是一个简洁的入门指南，但它确实简化了对 API 内容的描述。 github API 使用入门很简单，一些有用的功能包括：

1. 未登录状态下的测试使用
2. 获取公开的用户资料。
3. 用完整的请求头重复同一请求。
4. 对同一请求进行基本身份验证。
5. 使用基本身份验证来浏览你的个人资料。

然后指南进入到 OAuth 认证的问题后，不可否认这很复杂。开发者们这时已经经历了 5 次小小的成功，这让他们能更坚定的对待更困难的步骤。而很多入门指南一开始就是 OAuth，这更像是想让阅读者停止阅读。所以当你思考自己撰写的指南时，想想应该怎么从一个较简单的点开始，早一点让开发者们获得成功的喜悦。

Github 指南继续讲解库和问题，这对于使用他们 API 的开发者来说都是关键的部分。然后 Github 根据使用的情况为掌握基础后的开发者们提供明确的后续步骤。

特定语言指南


作为一个说英语的美国人，让我震撼的是出国旅行时别人都跟我说英语，尽管英语并不是那些人的母语。当我遇到针对特定语言像 javascript，python 或者其他语言的开发文档时，我有同样的感觉。所以最好的开发文档应该满足所有开发人员的需要，不管他们是谁，用的什么语言或框架，都为他们提供特定的指南。

在 StormPath 的文档首页，满屏都是语言选项。每一个语言都有快速开始按钮，完整的文档，一份 API 参考，一个 Github 项目甚至更多。这些资源都是针对特定语言或框架的。

StormPath 有 25 种针对不同语言或框架的资源页面。他们团队为创建和维护这些文档付出了很大努力，但是这为进入他们网站的不同开发人员提供了确切的指南。

供复制-粘贴的样例


针对不同的开发人员提供不同语言是快速入门的一种方式，另一种方式是提供让开发人员可以简单地复制粘贴的代码。你会发现很多开发文档中都有准备好的代码：你只需要在这里插入 API 开发密匙，或者添加适当的 cURL 命令完成 API 请求就能使用。尽量降低入门难度，以满足开发者需求。

Stripe API Reference很棒的一点就是，只需要复制粘贴文档上的例子，你就能准备好可使用的样例调用。每一个请求样例都包含了合适的cURL参数，一个API密钥，以及其他一个成功的API调用所需要的认证。最令人惊艳的是，你不需要登录，甚至都不要一个账号，你就可以获得一个成功的API调用。对，就是这样，Stripe为每一个访客创建了唯一的API密钥，提供了极低难度的上手方式让开发者使用它们的样例调用。

Stripe为它们的开发者做了很大的承诺,但这也就是为什么支付公司在提供一个极致的文档使用体验上是最顶尖的。这种方式不一定适合所有人，但是降低API上手难度并使API更容易使用是非常值得去做的。

API References


一旦开发人员了解某个API的基础用法，他们可能会放下文档转而去实现他们的逻辑。当他们回来时，他们是来寻找某个具体的问题的答案的。通常，他们会在API参考中找到答案——那些需要很容易被检索到的文档。

Clearbit文档易于浏览。由于它是在单一的页面中，是API参考中一个很好的功能，它是支持Ctrl+F/Cmd+F的。也就是说，你可以使用浏览器的查找功能进行搜索。每一节都在左侧的导航中详细显示，当你滚屏时会自动展开。Clearbit API参考的最右列专用于按语言分类组织的请求和响应示例。这些片段可以按原样复制和粘贴; 你只需要插入你的API关键字。

Clearbit API 文档最好的部分，你也可以做到和它一样。 Clearbit 的文档查看器是基于开源静态文档工具 Slate，您可以用它来构建您自己的易于浏览的文档。

Open Source-style Documentation


对于公司的其他人来说，拥有你的文档，确保其准确性，并在信息更改时进行更新——这些都是很重要的。 也就是说，你还应该向你的社区（使用你 API 或工具的开发人员）征求意见。 让别人更清楚地看到你做了什么，最好方法之一就是将您的文档视为开源项目。

当我在 SendGrid 时，我的同事 Brandon West 开源了他们的文档，主要基于以下原因：

现在有超过 200 个文档仓库的贡献者，多数来自公司外部。 此外，在 repo 开源的三年中，已经跟踪和修复了数百个问题。

这些结果听起来不错，但这都需要付出。对于初学者，从代码库的其余部分提取文档可能需要一些技术。但真正要做的是持续关注社区：回答问题、合并 pull 请求，并确保反馈给真正的内部团队。

Interactive Documentation 交互式文档


在我十几岁的时候，我打过篮球，但我更偏向理论型。我读过关于如何练习和改进的书。我曾在双腿之间的运球上栽了跟头。这曾被认为是一个炫耀的举动，但作者认为这是目前篮球运球的要求。交互式 API 用户就是开发文档的双腿运球爱好者。

漫画书公司 Marvel 的主文档是交互式的。一旦你有一个 API 关键词，你可以通过填写表单中的请求字段并单击“Try It Out!”按钮来模拟调用。响应的 JSON 将显示在表单下方，因为它返回和你的应用程序一样的数据。

交互式文档对 Marvel API 特别有用，它需要实时 API 调用的哈希值。Marvel 文档自动处理哈希值，使开发人员在提交 API 到代码之前就能查看结果。

建立这种文档也不一定很难。有许多交互文档平台，包括 Apiary 和 Readme 的托管解决方案，可帮助你制作自己的交互文档示例。

开发者博客


对文档最基本的期望就是它能准确的描述 API 或者开发者工具能干什么。本文中的很多示例都能把开发者带入门，但伟大的文档应该还能做到这么一件事：启发。没有什么开发者网站能像优秀的博客一样给读者带来灵感。

我们都是自己的开发者博客(你现在读的就是一个)的超级粉丝，但也会阅读其它博客。实际上，我们最近分享了 8 Resources for Keeping Up on APIs (让 API 保持最佳状态的 8 项资源)。其中比较有技术含量的最近一个是Auth0 博客。由于整个公司都在支持某个技术产品，这个博客偶尔还会提到公司产品的更新，但大部分文章的主题都是关于认证和安全。

Auth0 开发者博客的特别之处在于，并不是所有的东西都关于他们的产品。说明开发人员想要学习新的东西，所以他们分享知识，而不是功能。如果一个开发人员在阅读博客时学到了很多关于 JWT 令牌的知识，那么他们在实现该技术时一定会想到 Auth0。

如果可能的话，创建完美的文档是很困难的。但让文档变得更好却一点不难。这八个优秀文档的示例将是实施过程中的一个挑战。从今天开始， 改进你的入门指南，用语言组织你的文档，或在博客文章中传授一个小经验吧。