本文提出应根据受众需求对 API 文档进行分层：需要快速获取可操作信息的消费者，以及需要深入背景知识的维护者。同时主张通过直观的 API 设计和分层文档来提升实用性。
📝 详细摘要
作者反驳了“开发者不看文档”这一普遍的挫败感，指出文档之所以失败，是因为它混淆了两个截然不同的受众：API 消费者和 API 维护者。消费者需要快速、可扫描的信息来调用端点，而维护者则需要了解架构决策背后的“原因”。文章提出了一种“分层”文档策略，利用可折叠部分将操作指南与机构知识分离开来，并强调最好的文档是直观的 API 设计，从而最大限度地减少对解释的需求。
💡 主要观点
- 为两类不同的受众（消费者和维护者）分层编写文档。 API 消费者需要了解端点的功能及使用方法（需易于扫描），而维护者则需要架构背景和决策背后的“原因”（需深入剖析）。将两者混在一起会导致双方的文档体验都很差。
💬 文章金句
- “第一类是 API 的消费者……他们不是在像读一本书一样阅读你的文档。他们是在像看菜单一样扫描它。”
- “你所能做的最糟糕的事情，就是写一份试图同时服务于这两类受众的文档。”
- “文档的目标是在正确的时刻，将正确的信息传递给正确的人。”
- “就像你不会为每一行代码都写注释一样，文档也不会因为信息过多而受益。”
📊 文章信息
AI 评分：87
来源：iDiallo.com
作者：Ibrahim Diallo @dialloibu
分类：软件编程
语言：英文
阅读时间：5 分钟
字数：1153
标签： API 设计, 文档, 软件工程, 开发者体验, 技术写作