Readme.io 创始人谈 API 文档的未来

那些包含着相对较新工具的文档，比如 @Asciidoctor 和 Cyrille Martraire 的领域驱动设计启示书《动态文档》，是软件开发过程中被忽略的最大领域之一，如今终于得到了大家的些许关注。对于一个API 文档来说，其被认为是至关重要的。Gregory Koberger 正在开发一套系统，可以让开发者文档与API 和API 仪表盘更直接地对接。

最近InfoQ 采访了 Readme.io 的首席执行官 Gregory，为了实现他对于 API 文档的愿景，其创建了这家公司。

InfoQ**：您能描述一下创建Readme.io背后的故事吗，以及它是如何演化的？**

Gregory Koberger：当然可以，首先我是一名程序员及设计师，并且对开发工具感兴趣，因为在那片领域有着一套独特的设计挑战魅力。

我曾经花费了大量的时间用来写作和阅读文档，但是我认为应该有更好的方式实现它。大约五年前，我下定决心我要潜心专研这片领域，但是刚开始的时候我度过了一段艰难的时期。谢天谢地的是，像 Stripe 和 Twilio 这样的公司已经向人们展示了文档的重要性。大约一年前，我们成立了这家公司。

公司运行的非常好。我们也确实发现，一份更优秀的文档能够在某些产品和问题上发挥好的作用。我们正走向希望人们开始改变对文档的原有看法这一步。它不应该是一成不变的。它应该随着阅读它的群体和阅读群体的知识量而改变。

InfoQ**：您对Readme.io的愿景是什么？**

GK：API 由三部分组成：文档、仪表板（用来生成开发者密匙等）和 API 本身。

我想着手把它们整合到一起。API 了解代码和数据。仪表板了解用户。文档习惯上仍是一成不变，对它们一无所知。

比如，想象一下，如果文档知道用户语言，并且可以直接显示代码片段，或者想象如果文档知道用户犯了某个具体的错误，并能够帮他解决这个错误。

InfoQ**：当需要记录API时，您的API团队主要面临的挑战是什么？**

GK：一个大问题是, 记录 API 文档不是一个优先事项。人们包括我自己都非常不善于记录某个 API。很难回到从前，猜测新人在使用你的 API 时需要了解哪些东西。并且很难永远保持文档是最新可用的。

InfoQ**：Readme.io是如何帮助人们的？它的主要特点有哪些？**

GK：目前，我们主要专注于文档。就像 WordPress 专注于代码和 API 一样。我们让您在为客户提供开发体验时变得更加容易。

Readme 已经能够支持表单、登录页面、教程等等。我们让人们在在网页上正确地使用 API，进行变更，允许他们看看会发生什么。我们同样能够从 GitHub 上自动同步 API 文档并友好的展示出来。

InfoQ**：Readme.io与其它开源替代方案相比如何，比如Swagger UI或Slate？**

GK：Readme.io 有一个优势是公司的所有人都可以参与其中，不仅仅是开发者。很快我们将支持 Swagger，这样我们就可以替换 Swagger UI。同样我们认为，社区也应该参与到文档的记录过程中。因此，我们有一些建议性的编辑器：公司内部或者外部人员可以通过一个友好的拖放编辑器提交更改意见。

InfoQ**：Readme.io创建的文档可以部署到某个现有的开发者门户网站吗？**

GK：我们的目标是成为一个开发者中心。目前，你可以在一个现有的中心使用它。在未来，我们希望将文档，仪表板和支持整合到一块。当它们都在同一个地方时，它们真的会一起运行的很好。

InfoQ**：你们支持API定义语言吗？比如Swagger，RAML和API Blueprint。**

GK：是的。目前我们用一种叫做 APIdoc 的东西。不久我们将会发布对 Swagger ， RAML 和 API Blueprint 的支持。

与编写段落文本相比，通过语义上记录你的 API，你可以创造更多的价值。因为你可以着手给用户定制生成 SDKs 或者代码示例。

现在，我们仅限于导入这些语言，但是，我们认为让人们导出语言同样的重要。Readme.io 很幸运能够站在开发体验中心的舞台上，我们真的想利用这次机会成为不同 API 公司的交流中心。

InfoQ**：你们是如何支持各种API开发工作流的，是代码优先还是API优先？**

GK：通常，API 仅仅是以复制主网站构建的方式编写。那是一个很糟糕的事情，因为很多时候，你用 API 做一些网站不能做的事情。

所以，我认为将 API 看做网站的一个独立的实体是很重要的，因为你希望它足够的灵活，能够做一些网站不能做的事情。

InfoQ**：您认为哪种方式能最好的描述API，并且能够与其实现的演化相同步？**

GK：现在有很多种方法可以描述 API，比如 Swagger，RAML 和 API Blueprint。我们选择 APIdoc，是因为这种文档非常接近代码本身。它类似于 Javadoc，这种文档是对代码的一种注释，而不是一个单独的文件。我们可以从 GitHub 上自动同步。

InfoQ**：在一个典型的API团队中，谁应该负责记录API？**

GK：每一个人都应该。习惯上来讲，只有开发者做记录。但是，API 对业务、市场营销和产品管理团队同样非常重要。我们希望实现每个人从开发者到 CEO 都能够更新与他们相关联的文档。

我们认为社区对记录文档拥有难以置信的重要意义，因为他们有其他人所没有的疑问和用例。

InfoQ**：从您的观点来看，API文档和操作的API管理是否应该分开处理？**

GK：我真的很喜欢这个 API 的生态系统。现在有很多公司在做具体事情，并且做的很好。而对于较大的 API 管理公司，什么事都想自己做 但大部分做的很差。

我认为 API 管理和文档应该分开，但是，它们应该被更紧密的集成起来。

InfoQ**：请问Readme.io下一版本的推出时间和新功能有哪些？**

GK：我们正在做一个重大的重新设计工作，大约需要一个月左右的时间。除了看上去更加美观，我们将为参考指南和示例设置单独的版块。

对于文档编写人员，事情的发展和文档中应该包含哪些内容变的更加明显。对于终端用户，将会更容易知道从哪里获取他们想要的信息。

因为我们想着手自动化记录您 API 更多的过程，所以像 Swagger 导入之类的事变的非常重要。

大部分开发人员都要花费时间阅读或者编写文档。它是我们与代码库或 API 进行交互的界面，而且我真的很高兴 Readme 正变的有能力改变人们以往的方式。

你可以尝试免费版的 Readme.io ，并且它保留了免费的开源项目。对于专属软件，企业在 Readme.io 子领域提供了一个基本包，包括 3 个文档版本和一个管理员用户，花费 $14/ 月。开发者中心版本允许您使用自己的域名，并且支持 10 个管理员用户，花费 $59 / 月。

查看英文原文： Interview with Readme.io Founder on the Future of API Documentation

感谢张龙对本文的审校。

给InfoQ 中文站投稿或者参与内容翻译工作，请邮件至 editors@cn.infoq.com 。也欢迎大家通过新浪微博（ @InfoQ ， @丁晓昀），微信（微信号： InfoQChina ）关注我们，并与我们的编辑和其他读者朋友交流（欢迎加入 InfoQ 读者交流群）。