SDK 开发之文档

前言

作为一名 SDK 开发，回答业务咨询问题应该是日常工作中非常重要的一个部分了。在处理了一段时间的业务支持工作后，我发现不少在我们 SDK 开发看来非常显而易见和理所当然的问题也频繁地出现在业务咨询问题中，这类问题虽然处理起来不太复杂，但比较占用 SDK 开发的时间，也非常影响 SDK 使用人员的接入体验。为了降低这类问题被咨询的概率，我花了一段时间分析所有业务咨询问题和与业务开发人员交流，最后发现这类问题可以尝试采用优化官方文档和引导使用者查阅文档的方式进行解决。

如今我们的文档已经完成重构，显而易见的业务咨询问题也下降了50%+，现在借此博文将我对于 SDK 文档的理解记录下来，方便日后查阅。本篇文章首先会概要介绍什么是 SDK 和 SDK 文档及为什么需要写 SDK 文档，然后通过总结我们在优化 SDK 文档的过程中遇到的问题和采取的措施，思考一份好的 SDK 文档需具备什么特点，最后谈谈该如何书写和维护好 SDK 文档。

SDK 和 SDK 文档

SDK

维基百科显示，SDK 即软件开发工具包（Software Development Kit, SDK）一般是一些被软件工程师用于为特定的软件包、软件框架、硬件平台、操作系统等创建应用软件的开发工具的集合。

这个定义看上去比较抽象和难以理解，其实通俗来说，SDK 可以理解为一类提供给开发人员使用的工具，这类工具可以提高代码的复用率，提高业务开发人员的工作效率。

SDK 文档

理解了什么是 SDK 后，SDK 文档的概念就比较好理解了。SDK 文档是 SDK 开发者提供给 SDK 使用者的一份介绍 SDK 功能、应用场景、使用方法等信息的文档，其目的在于方便 SDK 使用者快速完成 SDK 的接入工作。

为什么需要写 SDK 文档

SDK 文档是 SDK 开发者向 SDK 使用者介绍其功能和使用方法的说明书，是连接 SDK 开发者和 SDK 使用者的桥梁。

对于 SDK 开发者：

SDK 文档能向广大的使用者介绍 SDK 功能，吸引更多的开发者使用 SDK；
SDK 文档能解决使用者遇到的不少问题，从而降低 SDK 开发者的业务支持工作量，以便将时间投入到功能开发、性能优化、技术提升等更有价值的地方。

对于 SDK 使用者：

SDK 文档能让他快速了解 SDK 的功能、适用范围和应用场景等，从而帮助他决定是否该采用此 SDK；
SDK 文档能让他了解如何将 SDK 接入到自己的应用中，及遇到问题时该如何处理，从而帮助他高效地完成功能接入。

因此，无论对于 SDK 开发者，还是 SDK 使用者，一份组织良好的 SDK 文档都是非常有必要的。

我们遇到的问题

虽然 SDK 文档很重要，但由于 SDK 文档质量并不直接影响开发者业绩，且开发者平时开发任务也比较重，导致不少开发者对这项重要而不紧急的工作并不在意。我们组也是如此，很长一段时间里，大家都只专注于完成功能开发，而没有将文档更新和维护工作放在心上，导致文档内容不完整、更新不及时，并没有很好地起到帮助降低业务咨询量的作用。

在我们更新和维护文档的过程中，主要遇到如下几类问题：

SDK 文档更新不及时：SDK 新版本功能上线后，文档还没有更新，导致使用者因不知该如何接入新功能，而放弃使用新功能，或需频繁和开发人员沟通才能完成功能接入；
SDK 文档描述和 SDK 注释不一致：SDK 文档描述内容和 SDK 代码注释内容不一致，导致使用者不知该相信哪部分内容，从而影响接入体验和效率；
SDK 文档内容不完整：部分必要内容未提供，如 SDK 适用平台、前置条件等，导致使用者不能确定是否能运用于自己的应用中，或误将 SDK 应用于不兼容的平台中；
SDK 文档结构不合理：SDK 文档根据语言而非功能划分文档结构，导致每份文档都非常冗长，文档更新时容易遗漏某门语言和出错，也使得 SDK 接入者需要在冗长的文档中查找自己需要的内容，费时费力；
SDK 文档内容错误：由于 SDK 功能开发者和文档更新者并不一定是同一个人，且文档更新并没有完善的内容审核制度，所以发布的 SDK 文档偶尔会出现内容描述不恰当或不正确的现象，导致接入者接收到不正确的信息。

针对上述几个问题，我们分别采取了如下几项措施，以尽可能完善官方文档质量：

建立文档更新机制：为了确保文档内容与 SDK 版本内容保持一致，我们建立了文档内容随版本发布而更新的机制。具体为：

a) 在需求澄清及转测阶段，均会更新需求单，以确定需求相关内容是否涉及官方文档修改，若涉及的话，应该如何修改;

b) 在版本上线前，进一步整理和确认官方文档修改内容；

c) 在版本上线时，同步更新官方文档。
版本比对：首先确保第一个版本的文档和注释内容一致，然后在之后的版本上线前，分别比对前后两个版本文档和注释内容的差异，并将差异部分校准，确保文档和注释内容一致；
提供意见反馈入口：建立类似 GitHub 的 pull request 机制，允许业务开发者向我们提交文档修改意见，我们在接收到意见后，及时修改文档；
重构文档：经过与 SDK 接入人员进行沟通与交流以了解他们的诉求、上网查阅其他开发人员的看法和意见及阅读业界优秀文档后，我们结合自身 SDK 的特点，重新梳理了文档结构，并完成了文档重构工作。

SDK 文档结构.png

好的 SDK 文档需具备什么特点

SDK 文档是提供给接入者查看 SDK 功能和接入教程的文档，其主要目的是为了方便 SDK 接入者使用 SDK，因此一份优秀的 SDK 文档应能很好地满足 SDK 使用者的诉求，采用恰当的方式提供给使用者所有他需要的信息。

一般而言，一份不错的 SDK 文档应具备如下特点：

实时性：文档更新及时，以便接入者能尽早使用新功能；
易用性：文档结构合理，描述清晰易懂，且会在必要的时候采用图表描述，方便理解，如提供 SDK 架构图、功能流程图等；
简洁性：最好不要在同一个文档中提供所有内容，而是根据文档结构和功能特点在不同的文档中分别提供各部分内容，并在文档中提供必要的跳转链接，建立模块间的联系，方便用户查看相关内容；
完整性：文档内容需完整而不冗余，应尽可能包含所有使用者需要了解的内容，而不提供与使用者无关的内容；
一致性：文档内容应与 SDK 及 Demo 内容保持一致，以免引起接入者理解困惑；
兼容性：更新后的文档应能与更新前的文档兼容，当涉及对已有功能的修改时，若前后版本使用不一致，最好在文档中区分版本，分别描述，而非直接更新到新版本；
参考性：文档最好能提供较为丰富的示例，如功能使用案例、代码示例、应用场景示例等，这些示例既能方便阅读者理解，又能降低接入错误概率。

如何书写和维护 SDK 文档

在这个信奉敏捷开发，快速迭代的互联网时代，一个优秀产品的诞生往往是不断迭代优化的结果。一份优秀的 SDK 也是如此，它并非一件一次投入即可完成的事情，而是需要持续不断地迭代和更新。因此需要建立比较完善的书写和更新机制，并始终坚持依照机制规范进行更新，才能尽可能确保 SDK 文档能始终维持比较好的质量。

经过一段时间摸索，我认为书写和维护 SDK 文档应遵循如下步骤：

多和用户沟通交流，了解用户诉求；
调研优秀文档应具备的特点，并多阅读业界优秀文档；
结合业界经验、用户心声和产品特点，制定文档规范；
将文档更新纳入到迭代规划中，建立文档定期和不定期更新机制，允许用户提交修改意见；
采用版本管理工具管理不同版本文档；
持续优化文档规范和更新机制，并遵循已有机制更新文档内容。