# 开发者文档的三种内容层次：字典、概览和教程

- Link: https://www.ixiqin.com/2022/12/27/developer-documentation-of-the-content-of-three-levels-an-overview-of-the-dictionary-and-tutorials/
- Published: 2022-12-27T06:00:00+08:00
- Author: 白宦成

文章目录

 [Toggle](https://www.ixiqin.com/2022/12/27/developer-documentation-of-the-content-of-three-levels-an-overview-of-the-dictionary-and-tutorials/#)

 * [第一层：解决有没有的问题](https://www.ixiqin.com/2022/12/27/developer-documentation-of-the-content-of-three-levels-an-overview-of-the-dictionary-and-tutorials/#%e7%ac%ac%e4%b8%80%e5%b1%82%ef%bc%9a%e8%a7%a3%e5%86%b3%e6%9c%89%e6%b2%a1%e6%9c%89%e7%9a%84%e9%97%ae%e9%a2%98)
 * [第二层：解决怎么用的问题](https://www.ixiqin.com/2022/12/27/developer-documentation-of-the-content-of-three-levels-an-overview-of-the-dictionary-and-tutorials/#%e7%ac%ac%e4%ba%8c%e5%b1%82%ef%bc%9a%e8%a7%a3%e5%86%b3%e6%80%8e%e4%b9%88%e7%94%a8%e7%9a%84%e9%97%ae%e9%a2%98)
 * [第三层：解决场景化使用的问题](https://www.ixiqin.com/2022/12/27/developer-documentation-of-the-content-of-three-levels-an-overview-of-the-dictionary-and-tutorials/#%e7%ac%ac%e4%b8%89%e5%b1%82%ef%bc%9a%e8%a7%a3%e5%86%b3%e5%9c%ba%e6%99%af%e5%8c%96%e4%bd%bf%e7%94%a8%e7%9a%84%e9%97%ae%e9%a2%98)
 * [第三层之后，应该是什么？](https://www.ixiqin.com/2022/12/27/developer-documentation-of-the-content-of-three-levels-an-overview-of-the-dictionary-and-tutorials/#%e7%ac%ac%e4%b8%89%e5%b1%82%e4%b9%8b%e5%90%8e%ef%bc%8c%e5%ba%94%e8%af%a5%e6%98%af%e4%bb%80%e4%b9%88%ef%bc%9f)

不知道，你有没有关注过开发者文档的信息结构。下图是 Google Docs 的 API 文档。

![](https://postimg.aliavv.com/mbp16/89ug0i.jpg)

在菜单中 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](https://developers.google.com/docs/api/reference/rest)
 * Slack API Reference [https://api.slack.com/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，只怕马上头皮发麻，需要每一个都看一遍才能理解其含义和价值；在
蓝牙这件事上阻塞个半周一周也是常态。

![](https://files.ixiqin.com/2023/01/23063410/d2b5ca33bd970f64a6301fa75ae2eb22-31-
539x1024.png)

一个好的 API Guide / Tutorial 可以有效的降低开发者在调试这些 API 过程中所耗费的时间。
当然，微信也意识到了这个问题，[提供了一套非常好的 API 说明](https://developers.weixin.qq.com/miniprogram/dev/framework/device/bluetooth.html)。

优秀的 Tutorials 参考

 * [https://api.slack.com/messaging/retrieving](https://api.slack.com/messaging/retrieving)

## 第三层：解决场景化使用的问题

典型案例：**Code Sample，Demo App，场景化的使用教程**

API Tutorials 可以解决的是面向场景化的单个领域的内容。它帮助开发者很好的解决了一个
领域内的产品能力的串联。但在实际的业务场景当中，开发者面对的不是已经拆解到 API 粒度
的任务，而是面向场景设计的不同问题。对于开发者来说，把场景拆分成 X 个 API 并没那么
容易（特别是如果经验不足的时候），因此，一套标准的 Code Sample ，甚至是 Demo App，
都可以帮助开发者快速解决面向场景化的问题。它可能涉及到了客户端、服务端，或者是面向
了多个不同的领域。这些内容帮助开发者可以快速 landing。

以飞书开放平台为例，飞书开放平台在开发教程里提供了多个领域、不同方向的场景化教程（
虽然还不够多，远远不够），帮助开发者快速完成某个特定领域的功能的开发。

![](https://files.ixiqin.com/2023/01/23063410/d2b5ca33bd970f64a6301fa75ae2eb22-32-
1024x506.png)

这些内容可能未必能完全满足开发者的需求，但确实可以给开发者一定的借鉴意义，帮助开发
者理解整个业务流程和对应场景下的具体的实现，帮助开发者快速完成业务需求。

## 第三层之后，应该是什么？

前面三层解决了有什么、怎么用的问题，而在整个应用的生命周期当中，怎么用并不是终极
问题。下一步需要解决的是如何用好的问题。不过这个问题不在本次阐述的内容当中，所以
我们留一个悬念，下次再说。