https://www.oschina.net/translate/great-documentation-examples?utm_source=tuicool&utm_medium=referral
你刚刚收到来自一位愤怒的开发者的电子邮件。你的文档有问题,开发人员花了几个小时才弄明白。现在轮到你更新文档,并找出如何在将来避免这些问题。 但是要怎么做呢?
创建出色的文档是很难的。致力于此通常意味着忽略了你工作的另一部分 - 而那段时间可能与开发工作一样有价值。每周几个小时改善文档可能会产生组合效应。开发人员陷入此种困境的频率会降低,请求支持的次数将会减少,并且老天保佑的话,愤怒式电子邮件也将减少。事实上,当你有很好的开发文档时,你甚至可能会经常收到快乐热情的电子邮件。
文档首页面向三类用户。 Heroku开发中心通过多种方式来帮助这三类用户找到他们需要的信息。 首先,在首页导航栏下面,用30号的字体来说明该网站的目的:学习如何在Heroku上创建,开发,管理你的应用程序。在这下面,列举了Heroku支持的8种开发语言。因此浏览首页后,开发人员立刻就能知道Heroku提供了什么,以及这里是否有他们需要的东西。
同时,主导航栏和副导航栏也帮助新开发人员使用该网站————解决问题、开始使用、或了解更多关于Heraku的信息。如果主页上没有吸引开发者的内容,或许这些详细列表里有他们需要的东西。如果都没有,那么就可以收集开发者的反馈信息,了解他们最需要什么,确保首页就能提供他们最需要的信息。
入门指南页面
快速入门指南在向开发人员介绍新技术方面有着重要作用,它也是使你的API广泛传播的最重要因素。 并且作为给开发人员的第一印象,制作入门指南需要格外用心。
GitHub 是一个具有很多高级用户的工具,尽管如此,用户的高知识水平也不该是制作复杂的入门指南的借口。 其入门指南超过 2,000 个字,这不是一个简洁的入门指南,但它确实简化了对 API 内容的描述。 github API 使用入门很简单,一些有用的功能包括:
-
未登录状态下的测试使用
-
获取公开的用户资料。
-
用完整的请求头重复同一请求。
-
对同一请求进行基本身份验证。
-
使用基本身份验证来浏览你的个人资料。
特定语言指南
作为一个说英语的美国人,让我震撼的是出国旅行时别人都跟我说英语,尽管英语并不是那些人的母语。当我遇到针对特定语言像 javascript,python 或者其他语言的开发文档时,我有同样的感觉。所以最好的开发文档应该满足所有开发人员的需要,不管他们是谁,用的什么语言或框架,都为他们提供特定的指南。
在 StormPath 的文档首页,满屏都是语言选项。每一个语言都有快速开始按钮,完整的文档,一份 API 参考,一个 Github 项目甚至更多。这些资源都是针对特定语言或框架的。
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 开源的三年中,已经跟踪和修复了数百个问题。
开发者博客
对文档最基本的期望就是它能准确的描述 API 或者开发者工具能干什么。本文中的很多示例都能把开发者带入门,但伟大的文档应该还能做到这么一件事:启发。没有什么开发者网站能像优秀的博客一样给读者带来灵感。
我们都是自己的开发者博客(你现在读的就是一个)的超级粉丝,但也会阅读其它博客。实际上,我们最近分享了 8 Resources for Keeping Up on APIs (让 API 保持最佳状态的 8 项资源)。其中比较有技术含量的最近一个是Auth0 博客。由于整个公司都在支持某个技术产品,这个博客偶尔还会提到公司产品的更新,但大部分文章的主题都是关于认证和安全。
Auth0 开发者博客的特别之处在于,并不是所有的东西都关于他们的产品。说明开发人员想要学习新的东西,所以他们分享知识,而不是功能。如果一个开发人员在阅读博客时学到了很多关于 JWT 令牌的知识,那么他们在实现该技术时一定会想到 Auth0。
如果可能的话,创建完美的文档是很困难的。但让文档变得更好却一点不难。这八个优秀文档的示例将是实施过程中的一个挑战。从今天开始, 改进你的入门指南,用语言组织你的文档,或在博客文章中传授一个小经验吧。