首页 > 分享 > 8 个最佳案例教你写好开发者文档

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

花匠小妙招
2025-04-23 18:52

加载中

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

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

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

开发者主页

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

想知道你提供了什么

想要开始进行开发

遇到困难想寻求帮助

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

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

入门指南页面

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

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

未登录状态下的测试使用

获取公开的用户资料。

用完整的请求头重复同一请求。

对同一请求进行基本身份验证。

使用基本身份验证来浏览你的个人资料。

然后指南进入到 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关键字。