使API文档工作所需的7个基本要素

本文概述

• API文档必须全面
• API文档必须足够吸引读者
• API文档必须正确划分为多个部分
• API文档必须正确放置
• API文档应该易于使用
• API文档应该是最新的
• API文档应该提供一些额外的东西

人们经常说, API价值的真正指标在于其文档的质量。 API文档被认为可以提高API的市场价值, 使API公司具有竞争优势, 并增加客户对该产品的信任度。毫无疑问, API开发的这一曾经被忽视的方面正逐渐成为现实, 并且开源和专有API文档工具都在升级。

但是什么时候可以认为他们的API文档非常有能力？到什么时候, API文档才能发挥作用, 吸引人并且最重要的是, 肯定会为API产品增加价值？如果你负责为公司的API产品编写托管API文档, 那么请务必牢记这些。密切关注这些元素将使你正确地创建有效的API文档。

API文档必须全面

一组API文档的第一件事就是它的完整性。无论采用哪种形式, 文档都应包含API调用, 端点, 参数和错误消息的完整列表。目标用户应该能够检查API文档并了解所有方面。

API文档必须足够吸引读者

任何产品的良好参考文件都会使读者觉得自己对产品的了解更好。 API文档肯定也是如此, 并且编写API文档的人员面临着针对复合受众的挑战。听众不仅可以包括开发人员, 还可以包括调试器, 客户端公司的决策者(产品经理, CTO等)以及API支持人员。但是, 一旦你的API团队在文档中的单词, 数字和符号之间取得了适当的平衡, 你将可以将它们进行大幅度的升级。

API文档必须正确划分为多个部分

理想的API文档还应该包含几个部分。其中包括快速入门指南, 教程, 通用主题, 基于上下文的示例和代码示例。尽管API文档的某些用户会从上到下阅读它, 但更常见的是, 他们会按部分进行浏览。确保他们在任何给定时间都可以轻松找到, 验证和测试他们想要的东西。

API文档必须正确放置

出色的API文档遵循动态而现代的布局。看起来过时的任何内容都可能给用户留下API不好的印象。有序地使用一些智能布局策略, 例如多列的节将上下文示例与端点进行镜像。

API文档应该易于使用

如果你的用户可以直观地了解如何使用它们并进行导航, 那么你的API文档是成功的。用户在API文档中寻找的一些东西是复制可粘贴性, 对不同编程语言的兼容性以及可导航性。考虑添加诸如语言选择器和粘性菜单之类的功能, 这些功能可帮助用户从一个区域导航到另一个区域。

API文档应该是最新的

文档应始终包含有关API版本, 新功能或升级功能以及已删除功能的详细信息。这就是向用户证明文档既不是过时也不是不正确的。幸运的是, 有许多软件工具可以加快API版本控制, 并且与版本相关的更新也很容易添加到API文档中。

API文档应该提供一些额外的东西

可以为你的API文档和API本身增加价值的一件事是存在一些额外的东西。一个流行的示例是可复制复制的”代码配方”或代码示例。这些文档可以包括与涉及你的API的真实情况有关的示例, 开发人员可以自己测试和定制。示例范围越广-这些示例与潜在用户越相关-你的API对他们的吸引力就越大。这只是一个例子, 在API文档中增加特权可以提高API的适销性。

如果你当前的API文档集满足这些条件, 那么你的API很有可能被采用。不要低估API文档增强产品整体价值和性能的强大功能。