如果你想让开发者像按下按钮一样完成集成，API 文档必须先懂他们的思维。

在我看来，最常见的误区是把文档当作一本《API 词典》来写。开发者不是在看词典，而是在解谜：先拿到凭证，调试请求，验证数据，最终把功能上线。文档就得跟着这个“实现旅程”走。

这里可以用一个经典的心智模型——“先入为主”来解释。人们在阅读时会优先捕捉与已知经验匹配的部分。于是，文档第一块内容最好放的是“快速开始”。Stripe 的“Quickstart”就是典型案例：一行 curl 命令，一段最小可运行的代码，立即让人知道接下来该做什么。

紧接着是“核心概念”。这里用“概念地图”模型。将 API 的主要资源（如 Users、Orders、Payments）用树形结构展示，旁边标注每个资源的 CRUD 端点和典型使用场景。这样开发者在阅读时可以快速定位要访问的“节点”。

再往下是“调用细节”。这里推荐“渐进式揭露”模型：先展示最常用的参数组合和默认值，再逐步展开高级配置。Google Cloud 的 REST API 文档就采用了这种层级：在每个方法页面顶部给出最小必需字段，下面是可选字段列表，最后是错误代码与重试策略。

别忘了“错误处理”这一块。把错误码与实际场景对应的“故事”插入进去，能大幅降低开发者的摸索成本。Twilio 的 API 文档里有一节专门列举常见错误，并给出解决步骤，读起来像是读一本手册而不是参考书。

从产品经理的角度，API 文档不仅是技术桥梁，更是“价值传递”的第一张牌。你需要问自己：我是否能在文档里让开发者看到最终价值？在 Stripe 的“成功案例”章节里，就把支付成功率提升的真实数据写进去，让开发者一眼看到自己的工作会带来什么样的商业回报。

最后，别忘了“反馈循环”。在文档底部提供一个“我遇到了问题，怎么办？”的链接，直接指向 GitHub issue 或 Slack 频道。这样你可以实时收集痛点，持续改进文档。许多开源项目的文档都遵循这个模型，用户社区的活跃度与文档质量呈正相关。

总结一下：按实现顺序排列，使用“先入为主”“概念地图”“渐进式揭露”“故事化错误处理”这几个心智模型，能让 API 文档不再是枯燥的技术手册，而成为开发者快速上手、快速产出的捷径。