# 什么是我眼中好的开发者产品的文档？（一） - Link: https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/ - Published: 2022-05-16T02:13:13+08:00 - Author: 白宦成 文章目录 [Toggle](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#) * [API Documentation vs Guide](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#api_documentation_vs_guide) * [一个好的 Guide 应该是什么样的？](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_guide_%e5%ba%94%e8%af%a5%e6%98%af%e4%bb%80%e4%b9%88%e6%a0%b7%e7%9a%84%ef%bc%9f) - [1. 一个好的 Guide 应该尽可能的显眼 & 好找](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#1_%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_guide_%e5%ba%94%e8%af%a5%e5%b0%bd%e5%8f%af%e8%83%bd%e7%9a%84%e6%98%be%e7%9c%bc_%e5%a5%bd%e6%89%be) - [2. 一个好的 Guide 应该有明确的步骤描述 & TOC](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#2_%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_guide_%e5%ba%94%e8%af%a5%e6%9c%89%e6%98%8e%e7%a1%ae%e7%9a%84%e6%ad%a5%e9%aa%a4%e6%8f%8f%e8%bf%b0_toc) - [3. 一个好的 Guide 应该是场景相关的](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#3_%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_guide_%e5%ba%94%e8%af%a5%e6%98%af%e5%9c%ba%e6%99%af%e7%9b%b8%e5%85%b3%e7%9a%84) * [一个好的 API Documentation 应该是什么样的？](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_api_documentation_%e5%ba%94%e8%af%a5%e6%98%af%e4%bb%80%e4%b9%88%e6%a0%b7%e7%9a%84%ef%bc%9f) - [1. 一个好的 API Documentation 应该是组织合理的](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#1_%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_api_documentation_%e5%ba%94%e8%af%a5%e6%98%af%e7%bb%84%e7%bb%87%e5%90%88%e7%90%86%e7%9a%84) - [2. 一个好的 API Documentation 应该具备所涉及到的各项数据结构的说明](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#2_%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_api_documentation_%e5%ba%94%e8%af%a5%e5%85%b7%e5%a4%87%e6%89%80%e6%b6%89%e5%8f%8a%e5%88%b0%e7%9a%84%e5%90%84%e9%a1%b9%e6%95%b0%e6%8d%ae%e7%bb%93%e6%9e%84%e7%9a%84%e8%af%b4%e6%98%8e) - [3. 一个好的 API Documentation 应该提供相应的 Sample Code](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#3_%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_api_documentation_%e5%ba%94%e8%af%a5%e6%8f%90%e4%be%9b%e7%9b%b8%e5%ba%94%e7%9a%84_sample_code) - [4. 一个好的 API Documentation 应该可以提供上下游关系](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#4_%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_api_documentation_%e5%ba%94%e8%af%a5%e5%8f%af%e4%bb%a5%e6%8f%90%e4%be%9b%e4%b8%8a%e4%b8%8b%e6%b8%b8%e5%85%b3%e7%b3%bb) - [5. 一个好的 API Documentation 可以提供用户之间的沟通渠道](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#5_%e4%b8%80%e4%b8%aa%e5%a5%bd%e7%9a%84_api_documentation_%e5%8f%af%e4%bb%a5%e6%8f%90%e4%be%9b%e7%94%a8%e6%88%b7%e4%b9%8b%e9%97%b4%e7%9a%84%e6%b2%9f%e9%80%9a%e6%b8%a0%e9%81%93) * [总结](https://www.ixiqin.com/2022/05/16/what-is-learned-from-wp-developer-reference/#%e6%80%bb%e7%bb%93) 我自己作为开发者使用过很多的开发产品，也看过不少的文档。最近频繁受邀针对不同的产品 的文档提出建议，单独写这样一篇文章来说明一下我觉得什么是好的文档。一方面，可以帮助 更多的开发者产品变得更好，另一方面，也可以用于自省，我自己在设计产品时是否会有类似 的问题。 **_不过也需要注意，这篇文档仅涉及 「Guide」和「API Documentation」的部分，对于更多 的 Changelog、Example、Tools 、 SDK 则没有涉及，这部分留待后续再写。_** 本文当中参考了包括：[Notion 开发者文档](https://developers.notion.com/)、[微信小程序开发者文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)、 [声网 Agora 开发者文档](https://docs.agora.io/cn)、[WordPress 开发者文档](https://developer.wordpress.org/reference/)、 [飞书开发者文档](https://open.feishu.cn/document/home/index)等开发者产品。 ## API Documentation vs Guide 其实不少的产品文档写的都是 API Reference ，而不是 Guide，二者在实际的使用意义上是 有所不同的。 * Guide 帮助开发者快速上手一件事，从 0 开始，完成一件事。这是**「用户视角」**。 * API Reference 则是告诉开发者你能使用我的产品做什么事情。这是**「平台视角」**。 一个好的文档应该是二者兼备的，这样才能一方面降低开发者的进入门槛（Guide 负责）， 另一方面， 可以让开发者可以知晓能力的范畴，帮助开发者尽可能拓展的应用边界，创造出 美好的体验和新的世界。 ## 一个好的 Guide 应该是什么样的？ 这里我们以 Notion 的文档为例： ### 1. 一个好的 Guide 应该尽可能的显眼 & 好找 作为一个新的开发者，进入一个新的开发者平台时时迷茫的：“我应该做什么？”、“我应该看 什么？“ 这时一个明确的「Guide」、「Get started」可以帮助我们快速找到一个开始的锚点，这个 锚点会成为开发者在这个平台中开始进行的下一步。 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-11- 1024x517.png) Notion 开发者文档首页中 Guides 的入口 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-12- 1024x444.png) 微信小程序开发者文档中的指南的入口 ### 2. 一个好的 Guide 应该有明确的步骤描述 & TOC 开发者在进入一个新的平台时，需要的是「快速跑完流程，以熟悉平台的各项基本功能」， 而不是需要了解到所有的能力（如果开发者已经非常熟悉你的产品，其实根本不会看 Guide， 直接去对应的 API Documentation 查看实现了）。 **一个明确的步骤描述和 TOC 可以帮助开发者降低心理压力，并让用户找到自己所在的位置， 进行下一步的推进**。步骤的名称也非常的重要，一个清晰明确的步骤，可以帮助开发者快速 明确自己要做什么事情，不会产生疑惑。 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-13- 1024x427.png) Notion 文档当中对于步骤描述 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-16- 1024x439.png) 声网文档中关于步骤的描述 此外，也需要注意，步骤不建议太多，可以移除掉那些非核心的步骤，**重要的是帮助用户 跑通开发流程**。 ### 3. 一个好的 Guide 应该是场景相关的 开发者在使用产品进行产品开发时，会有明确的预期，我要做什么事情。但产品需求和平台 的能力是不同的。我们很难将产品需求和平台能力直接挂钩，这时就需要开发者盲人摸象般 在整个平台上搜索和查看，找到适合自己的文档。这个时候，如果有一个场景相关的 Guide， 可以帮助开发者快速找到适合自己的场景，并进行文档的细分。 在这些文档中，你的目的是帮助开发者快速了解在你平台上某个方向的能力、核心概念和如何 组合你所提供的能力，帮助开发者快速实现自己的业务诉求。 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-15- 1024x447.png) Notion 文档中的场景化文档 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-18- 1024x449.png) 微信开发者平台的场景化介绍 ## 一个好的 API Documentation 应该是什么样的？ 如果说 Guide 是开发者进入一个平台的时候最基础的教程文档。API Documentation 则是一个 开发平台中最为核心的部分了，开发者每天都需要与 API Documentation 打交道，以完成一项 工作，如果 API Documentation 做的不好，那对于开发者来说，简直就是一个灾难。 ### 1. 一个好的 API Documentation 应该是组织合理的 API Documentation 当中往往包含了大量的信息，那么合理的拆分不同的 API 的模块，可以 帮助开发者无需遍历所有的 API ，而是直接按照模块逐级查找自己所需的 API 即可，可以 有效的提升查找的效率。 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-19- 1024x589.png) Notion 文档当中按照业务模块拆分的 API Documentation ### 2. 一个好的 API Documentation 应该具备所涉及到的各项数据结构的说明 对于复杂的 API 接口来说，参数/返回值往往不仅仅是一个简单的 Integer 、String ，还 会涉及到一些更加复杂的结构化数据的定义。 一种选择是将这种复杂的结构化数据抽象出来，成为一个新的类型；另一种选择是每次都解释 一遍。显然，根据软件工程的 “DRY” 原则，我们应当将其抽象出来。在将对应的数据结构抽象 出来后，需要注意的是，将其放在一个明确的位置进行展示和说明。**原则上，这些结构的 说明应该先于具体的接口说明。** ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-20- 1024x391.png) Notion 文档中的 Database Object 的位置说明 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-21- 1024x773.png) WordPress 文档中关于返回类的定义描述 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-22. png) WordPress 中在返回值中说明的错误类的入口 ### 3. 一个好的 API Documentation 应该提供相应的 Sample Code 对于开发者来说，**Talk is cheap, show me code**。而在开发领域也是同样的。你提供的 Sample Code （甚至是在线的调用测试），都可以帮助开发者更好的理解相关的能力和开发 逻辑。 **所有的细节，都在 Sample Code 中一览无余。** ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-23- 1024x554.png) Notion API Documentation 中生成代码的部分 ### 4. 一个好的 API Documentation 应该可以提供上下游关系 在 WordPress 文档中，有一个我非常喜欢的功能就是 **Related** 。Related 内部分为 ** Uses **和 **Used By**，分别介绍了某个函数都是用了哪些函数来完成自己的功能和哪些函数 使用本函数完成自己的功能。 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-24. png) WordPress 文档中 Related 的部分说明 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-28- 1024x434.png) 声网文档中关于 API 上下游的描述 伴随着 Uses 还提供了这个函数的源码（不过这个对于平台类型的产品不能直接照抄），这样 我可以非常清晰的参考这个函数的 Uses 和源码，以了解这个函数是如何实现自己的功能的。 这样当我需要的时候，就可以非常方便的基于这个函数，改造出一个我自己使用的函数。 而 Used By ，则提供了其他的函数是如何使用这个函数的。对于一些我比较陌生的函数，可以 直接参考其他函数的用法。从某种意义上来看，**这是比测试用例更加全面的用法的说明， 因为这是在“生产环境”下的用法。** 我们在开源世界如果没有文档，会看测试用例，那么在 WordPress 当中，我会看的是 Used By。 ### 5. 一个好的 API Documentation 可以提供用户之间的沟通渠道 我在 WordPress 开发者文档当中，还会常用到的一个功能是 —— User Contributed Notes。 这个功能为开发者提供了一个基于函数的共建笔记。开发者可以自发的在其中撰写自己针对 这个函数的开发经验。 ![](https://files.ixiqin.com/2022/05/23063052/d2b5ca33bd970f64a6301fa75ae2eb22-25- 1024x787.png) WordPress 文档中 User Contributed Notes 当我在不知道某个函数应该怎么使用的时候，我往往会去 User Contributed Notes 去找找 看，看看别人是如何使用某一个函数的。官方的文档往往无法跳出「我有什么」的思路，而 用户的共建笔记则可以共享出开发者使用某个函数的「奇技淫巧」。这些「奇技淫巧」让开发 者的产品显得与众不同，也可以进一步的扩大产品的范畴。 ## 总结 一个好的开发者产品文档是什么样的我很难定义，但至少上述的这些点，确实让我使用这些 平台的产品在开发应用和业务的时候变得更加坚定。希望我的这些笔记，可以帮助到你，让 你也可以涉及出一个好的开发者文档。