💡 Key Takeaways
- The $2.3 Million Documentation Problem Nobody Talks About
- The Five-Minute Rule: Why First Impressions Are Everything
- The Curse of Knowledge: Why Engineers Write Terrible Documentation
- Code Examples: The Most Important Part of Your Documentation
没有人谈论的230万美元文档问题
我是Sarah Chen，过去11年我在三家不同的以API为中心的公司担任开发者体验工程师。在2019年，我看着一家B轮创业公司耗费230万美元的工程资源构建他们所称的“物流API的Stripe”。该产品确实具有创新性——实时包裹追踪，延迟低于一秒，预测交付窗口和无缝的承运人集成。发布六个月后，他们有47名开发者注册。实际上只有十二人进行了集成。到第九个月，只有三个人仍在使用它。
💡 关键要点
- 没有人谈论的230万美元文档问题
- 五分钟规则：为什么第一印象至关重要
- 知识的诅咒：为什么工程师写出糟糕的文档
- 代码示例：您文档中最重要的部分
问题不在于API。我知道，因为我自己进行了负载测试。问题在于他们的文档——一本127页的PDF，读起来就像法律合同和计算机科学教科书的结合。没有代码示例。没有快速入门指南。只有假设你已经完全知道自己要构建什么的端点描述。
那家公司已经不存在了。但这种模式？我到处都能看到。我在职业生涯中审核了超过200个API的文档，为34家公司提供了开发者体验策略咨询，而让我寝食难安的是：大多数API提供商认为他们的文档很好。他们错了。这让他们损失惨重。
您的API文档不仅仅是个锦上添花的东西。它不是您发货后再添加的东西。这是开发者选择您API或竞争对手的区别。它是15分钟的集成和三天的调试噩梦之间的区别。而现在，如果您正在阅读这篇文章，您的文档有73%的机会正在积极阻止开发者使用您的API。
我知道这个数字听起来像是虚构的。其实不是。这来自于我在2023年进行的一项研究，其中包括来自23个国家的1847位开发者，问他们一个简单的问题：“您是否曾因为糟糕的文档而放弃过API集成？”结果是毁灭性的——这应该让每个API公司感到恐惧。
五分钟规则：为什么第一印象至关重要
这是大多数API公司不明白的事情：开发者在阅读您的文档的前五分钟内做出关于您API的去留决定。不是五个小时。不是五天。是五分钟。
“文档不是发布后的任务——它就是产品。如果开发者在十五分钟内无法理解您的API，他们就会选择一个能够理解的。”
我在第二份工作中吃了这个苦头，那是为一家与Stripe直接竞争的支付处理API工作。我们的费率更低，结算时间更快，欺诈检测更灵活。我们本应赢得竞争。然而，我们的集成率仅为Stripe的八分之一。我花了三个月时间对评估过两个平台的开发者进行了访谈，模式非常清晰。
在Stripe，开发者可以复制粘贴一段代码片段，运行它，并在不到三分钟内看到成功的测试交易。而使用我们的API，他们必须阅读身份验证文档，理解我们的Webhook签名验证系统，配置环境变量，然后——也许——获得成功的响应。实际的API调用几乎是相同的。文档体验却天差地别。
我进行了一个实验。我坐在单向玻璃后，观察50位开发者第一次评估我们的API。我给他们一个简单的任务：“创建一个10美元的测试付款。”我计时。成功的平均时间为23分钟。有12位开发者完全放弃了。当我问他们为什么时，最常见的回答是：“我不知道从哪里开始。”
那时我理解了五分钟规则。如果开发者在访问您的文档后五分钟内无法获得成功的API响应（任何响应），您就失去了他们。他们会告诉自己以后再回来。他们不会。他们会评估您的竞争对手。
解决方法并不复杂。我们创建了一个“快速入门”部分，位于文档的最顶部。它有一个明确的目标：让开发者尽快获得成功的API调用。我们为测试提供了一个预配置的API密钥，一个curl命令和预期响应。第一次成功的时间缩短到2.7分钟。下一季度集成率提高了340%。
知识的诅咒：为什么工程师写出糟糕的文档
让我告诉你关于Marcus的事。Marcus是一家我咨询的金融科技公司的优秀后端工程师。他构建了他们整个API基础设施——身份验证、速率限制、Webhook交付，所有一切。当需要编写文档时，他是显然的选择。他比任何人都更了解系统。
| 文档方法 | 首次集成的时间 | 开发者保留率（90天） | 每用户支持工单数 |
|---|---|---|---|
| 仅限PDF文档 | 3-5天 | 12% | 8.3 |
| 基本参考文档 | 1-2天 | 34% | 4.7 |
| 带示例的交互文档 | 2-4小时 | 67% | 1.9 |
| 快速入门 + SDK + 实时玩耍区 | 15-30分钟 | 89% | 0.6 |
他提供的文档在技术上准确、全面，但完全无法使用。以下是他身份验证部分的实际句子：“使用您的秘密密钥实现HMAC-SHA256签名验证，以验证Webhook有效负载的完整性，然后再处理事件。”这句话假设您知道什么是HMAC，SHA256是什么意思，为什么Webhook需要签名验证，以及如何在您选择的语言中实现它。
Marcus并不是故意刁难。他正受到知识的诅咒的影响——一种认知偏差，专家忘记了不知道某件事的感觉。当你花了两年时间构建一个API时，每个概念都显得显而易见。当然开发者知道什么是HMAC。当然他们理解Webhook签名验证。可实际上，他们并不明白。
我经常看到这种模式。由构建API的工程师撰写的API文档几乎总是过于技术化、术语太多，并过于关注系统如何工作，而不是如何使用它。解决方案不是降低门槛——而是要记住，您的受众不是您自己。
在那家金融科技公司，我实施了一条简单的规则：没有工程师可以在未经观察一位从未见过API的开发者使用它的情况下发布文档。我们录制了这些会议。我们让工程师观看开发者与他们的文档斗争。这很不舒服。但这也是一种变革。
在观看了一位开发者花费15分钟尝试弄清楚如何格式化日期参数后，Marcus重写了那一部分。 invésde “日期必须符合ISO 8601标准”，他写道：“使用这种格式的日期：2024-01-15T14:30:00Z。以下是在Python中生成此格式的方式：datetime.utcnow().isoformat() + 'Z'。”相同的信息。完全不同的体验。
代码示例：您文档中最重要的部分
我想说一个有争议的声明：如果您的API文档中没有至少五种编程语言的代码示例，您就排除了60%的潜在用户。我知道这是因为我一直在跟踪它。
“每缺少的代码示例都让您失去用户。每个令人困惑的端点描述都让您失去集成。您对开发者知识的每一个假设都让您失去收入。”
在我目前的角色中，我们支持Python、JavaScript、Ruby、PHP、Java、Go和C#的代码示例。我们跟踪开发者最常复制的示例。Python和JavaScript占所有复制的67%。但有趣的是：当我们在2022年添加Go示例时，来自关注DevOps的公司的集成增加了28%。当我们添加C#示例时，企业采用率增加了41%。
您选择展示的语言很重要。如果您唯一的代码示例是curl，那么您实际上是在告诉开发者：“自己弄懂其余的。”如果您只显示JavaScript，那么您就是在说：“这个API是面向前端开发者的。”如果您只展示Python，后端开发者会进行集成，但移动开发者甚至不会考虑您。