S1E3 开发者文档的三种内容层次：字典、概览和教程
Hi，欢迎收看 APILetter，距离上一次更新，已经过去了三周。天津疫情凶猛，今天我终于又来到了街上。现在正在天津大悦城的星巴克臻选里写这封邮件。
不知道，你有没有关注过开发者文档的信息结构。下图是 Google Docs 的 API 文档：
在菜单中 Google Docs 提供了 Home、Guides、Reference、Samples、Support。你有没有想过，这些内容为什么如何设计？在我看来，这是开发者文档内容的三种层次。
第一层：解决有没有的问题
典型代表：API Reference
绝大多数开放平台也好，To Developer 产品也罢，首先要解决的问题是让开发者知道我有什么样的能力。而最简单、最直接最高效的方式，便是 API Reference。
各大产品在进行对外开放时，首先准备的便是一套 API Reference。在 API Reference 当中，你可以看到开发者应该如何调用一个 API；某个 API 的入参是什么、出参是什么；如果出现了失败，应该如何处理这些错误。
当一个 API Reference 为开发者提供了简洁、明确、易懂的文档内容之后，开发者基本就可以准备开始进入开发流程了。
Opinionated Notes：RESTFul API 的 API Reference 理论上不应该存在多层级的资源关系。
优秀的 API Reference 参考：
- Google API Docs https://developers.google.com/docs/api/reference/rest
- Slack API Reference https://api.slack.com/reference
第二层：解决怎么用的问题
典型代表：API Overview、单个业务领域的 API Guides & API Tutorial
作为开放平台，当完成了 API Reference 之后，便算是及格了。但及格不应该是目标，目标应当是卓越。抵达卓越，则需要更多内容的帮助。
API Reference 回答了「能用什么」的问题，但没有解决「如何使用 API」的问题，特别是复杂的业务场景下，同一个业务内可能会需要多个不同的资源来进行 API 的操作，这个时候，如何使用这些资源，并将这些资源包装、关联起来，就成为极具业务属性的 Know How 知识。
举个例子来说，以服务端 OpenAPI 为例，日历的资源就涉及到用户、日历、日程、会议室、参会人、权限管控等多个不同的资源，如何串联这些 API 才能达成你的业务目标，就成为一个非常重要的说明。对于日历的能力熟悉的开发者可能很快就可以找到调通的方式，但对于不够熟悉的，这些 API 之间的串联，可能需要他花费一天，甚至一周的时间才能真正理解背后的含义。如果想要降低开发者调通过个 API 的时间，那么介绍这些不同 API 之间的关系，其在业务系统之中的含义就尤为重要。
如果你对于服务端的 API 感触不深，那么客户端的 API 可能会让你感受更加深刻，以微信小程序的中的蓝牙设备开发为例，如果你作为一个从未开发过蓝牙能力的开发者，看到了蓝牙提供的这一系列 API，只怕马上头皮发麻，需要每一个都看一遍才能理解其含义和价值；在蓝牙这件事上阻塞个半周一周也是常态。
一个好的 API Guide / Tutorial 可以有效的降低开发者在调试这些 API 过程中所耗费的时间。当然，微信也意识到了这个问题，提供了一套非常好的 API 说明。
优秀的 Tutorials 参考
第三层：解决场景化使用的问题
典型案例：Code Sample，Demo App，场景化的使用教程
API Tutorials 可以解决的是面向场景化的单个领域的内容。它帮助开发者很好的解决了一个领域内的产品能力的串联。但在实际的业务场景当中，开发者面对的不是已经拆解到 API 粒度的任务，而是面向场景设计的不同问题。对于开发者来说，把场景拆分成 X 个 API 并没那么容易（特别是如果经验不足的时候），因此，一套标准的 Code Sample ，甚至是 Demo App ，都可以帮助开发者快速解决面向场景化的问题。它可能涉及到了客户端、服务端，或者是面向了多个不同的领域。这些内容帮助开发者可以快速 landing。
以飞书开放平台为例，飞书开放平台在开发教程里提供了多个领域、不同方向的场景化教程（虽然还不够多，远远不够），帮助开发者快速完成某个特定领域的功能的开发。
这些内容可能未必能完全满足开发者的需求，但确实可以给开发者一定的借鉴意义，帮助开发者理解整个业务流程和对应场景下的具体的实现，帮助开发者快速完成业务需求。
第三层之后，应该是什么？
前面三层解决了有什么、怎么用的问题，而在整个应用的生命周期当中，怎么用并不是终极问题。下一步需要解决的是如何用好的问题。不过这个问题不在本次阐述的内容当中，所以我们留一个悬念，下次再说。
如果你对于这个话题感兴趣，欢迎回信聊聊。
