开源中国

我们不支持 IE 10 及以下版本浏览器

It appears you’re using an unsupported browser

为了获得更好的浏览体验,我们强烈建议您使用较新版本的 Chrome、 Firefox、 Safari 等,或者升级到最新版本的IE浏览器。 如果您使用的是 IE 11 或以上版本,请关闭“兼容性视图”。
8 个最佳案例教你写好开发者文档 - 技术翻译 - 开源中国社区

8 个最佳案例教你写好开发者文档 【已翻译100%】

标签: <无>
oschina 推荐于 6个月前 (共 15 段, 翻译完成于 06-02) 评论 2
收藏  
157
推荐标签: 待读

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

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

Tocy
 翻译得不错哦!

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

开发者主页

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

  1. 想知道你提供了什么

  2. 想要开始进行开发

  3. 遇到困难想寻求帮助

cassia_
 翻译得不错哦!

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

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

cassia_
 翻译得不错哦!

入门指南页面

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

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

  1. 未登录状态下的测试使用

  2. 获取公开的用户资料。

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

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

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

cassia_
 翻译得不错哦!

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

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

边城
 翻译得不错哦!

特定语言指南

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

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

cassia_
 翻译得不错哦!

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

供复制-粘贴的样例

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

cassia_
 翻译得不错哦!

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

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

kailuncen
 翻译得不错哦!

API References

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

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

Tocy
 翻译得不错哦!

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

    Open Source-style Documentation

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

狗德儿
 翻译得不错哦!
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们
评论(2)
Ctrl/CMD+Enter

看到“复制-粘贴的样例”,才发现原来之前比较火的某++支付聚合,也是抄人家的。服务抄,网站抄,连API文档的说明页面也是抄的一模一样,不得不服。看来都是在向腾讯学习
Git 管理, 格式用 markdown/asciidoc, 在线生成 GitBook 就行了。
顶部