编写API文档的新方法

世界上最伟大的 API 有许多相似之处和不同之处，但几乎所有 API 都有一个共同点：出色的文档。如果没有可靠的文档，API 集成可能会是一场噩梦，迫使许多开发人员放弃。无论如何，API 文档的重要性怎么强调都不为过。

在我们2024 年奥斯汀 API 峰会上， Nylas 的技术撰稿人劳拉·鲁宾与我们一起讨论了如何改善读者和作者的文档体验。据 Rubin 说，消费者的期望与匆忙拼凑的文档的现实之间往往存在脱节。下面，我们将介绍 Rubin 演讲中的要点和一些可行的见解。

确定更好的文档需求

在评估 API 文档的质量时，需要考虑许多不同的标准。Rubin 在演讲中指出了一些通常表明文档需要一些改进的情况：

• 实施时间较长或放弃率较高。
• 您在开源项目上拥有大量支持票或 GitHub 问题。
• 完成销售需要很长时间（例如API 即产品）
• 用来衡量客户体验的指标净推荐值 (NPS) 较低。

讽刺的是，她说，快速增长往往会导致这些问题。一般来说，增长对小公司来说是一件好事。然而，它可能会导致高压环境，需要快速周转时间，组织空间很小。不幸的是，这种轨迹可能导致 FUD——恐惧、不确定性和怀疑。

“当一群人分散撰写文档时，就会发生这种情况。你不知道是谁写的、什么时候写的、为什么写的、是否写完了、是否有人编辑过它，”鲁宾说。这导致人们花费更多时间与工具链作斗争或弄清楚他们需要在哪里写作，而不是真正开发有用的内容。

当然，知道您的文档需要改进只是成功的一半。下一步是弄清楚您应该在何处以及如何改进它们。

找到正确的改进领域

开发人员对自己所从事的产品非常熟悉，缺乏新手的全新视角，因此很难回答这个问题：“新人能否仅通过阅读文档就弄清楚如何使用你的产品？”Rubin 建议寻求新员工的帮助，前提是他们在申请过程中没有被要求使用你的 API。

常见的用户体验问题

但是，正如 Rubin 所观察到的，“文档并不能替代良好的开发实践。”有时，文档人员可以围绕令人沮丧的用户体验问题进行撰写，但并非总是如此。“如果你与工程师密切合作，”她建议，“那么现在就应该说，‘与其称之为 ID，我们能不能称之为日历 ID，这样更清楚？’”

提供反馈

另一种方法是通过分析仪表板、搜索日志和其他可以让你真正了解他们在做什么的东西来查看他们的行为。你还可以查看跳出率或从不同来源引用的页面数量。“这类东西不会说谎，”鲁宾说。

通用文档提示

经验丰富的技术作家

但她也鼓励缩小范围，采用更全面的方法来编写 API 文档。“您可以拥有一个描述完美的端点，但如果您不知道它如何与其他端点配合，它看起来就像一团乱麻，而用户真正想要的是说明。”

“要有条理，”她继续说道。“即使只是按字母顺序排列。读者总是会认为这种顺序是有目的的，他们会试着猜测是什么……直到他们试遍了他们能想到的所有方法，并认为你只是把事情弄得一团糟。”

因此，作者应该考虑采用多方面的方法来改进文档。除了考虑读者之外，Rubin 指出，我们还需要考虑维护者：“一旦你有了好的文档，”她说，“维护文档的人的可用性就是你保持文档良好的方法。”

实际上，这是什么样的呢？

• 拥有文档、共同拥有文档或将其拆分并拥有文档。“如果这是每个人的工作，那么就没有人的工作了。”
• 把事情写下来。为未来的维护者详细说明“如何”和“什么”。
• 追求进步胜过​​追求完美。不要害怕反复的过程。
• 有主见的工具。插件、linters 和自动化工具将在未来减少决策疲劳。
• 一致性。建立一个用户可以在所有产品或服务中遵循的心理模型。

关于最后一点，她呼应了克里斯汀·沃马克 (Kristin Womack) 在我们 2023 年平台峰会上的演讲中倡导的“类似走廊”模型。“即使你不这么认为，”鲁宾警告说，“读者总是在 [寻找模式] 并构建你的文档的心理模型。”

像作家一样思考（因为你就是作家！）

正如 Rubin 指出的那样，好的写作对于好的文档至关重要。尽管我们可能不认为 API 文档与伟大的美国小说相提并论，但在这种情况下，“好的写作”与我们可以从 Ernest Hemingway 或 John Steinbeck 等小说家的简洁散文中期待的许多特征相同：

• 省略不必要的词语。
• 避免使用过去时和被动语态。
• 使用简单的词语，避免使用俚语。鲁宾建议使用全球英语，这是一种文字和逻辑的写作形式。
• 逐步披露。换句话说，不要倾倒信息。
• 在没有必要的情况下不要使用复杂的术语。
• 鲁宾说，要表现出自信。“不要说‘这应该能得到 200 分。’要有信心！它确实能得到。”

随着 API 通过版本控制和弃用不断发展，其文档也应如此：良好的文档是一段旅程，而不是目的地。越早开始将文档视为周期性编写、使用和编辑，迭代过程就会变得越轻松。

关于这一比较的最后一个想法是：像一位伟大的作家一样思考意味着少考虑自己，多考虑你的读者。他们期待什么？他们习惯了哪些惯例？他们“理解”了你讲述的故事吗？所有这些都是在应用现有的最佳实践的同时进行的。

好吧，创建出色的文档很不容易！

原文地址：https://nordicapis.com/a-new-approach-to-writing-api-documentation/