SDK开发经验之文档

为什么要有

关于为什么要有文档，觉得所有人应该都懂，想总结一下发现总结不了，于是就去百度和知乎了一下。附上知乎链接：http://www.zhihu.com/question/27084608

文档是官方提供的，所以具有无以伦比的权威性；文档是起说明式作用的，所以你想要知道什么，文档都会给你提供。

仅仅通过他人的口述、视频、实例往往无法完整的了解到SDK的接口的所有的作用，好比盲人摸象，你对它的认知、印象、经验将完完全全从他人所提供的教程中继承而来。而帮助文档能够客观、全面地介绍出它所包含的所有内容，能够辅助你学习如何“使用”它。这就是API的重要性和阅读API能力的重要性。

我们遇到的问题

我们的SDK做了这么久，被开发商嗤之以鼻最多的问题之一就是文档。主要表现在：

问题的原因比较多，主要是三个方面：

• 没有完整的线上文档，所有的接口文档都是跟随版本包。
• 由于支持的游戏很多，因此同一时间内我们外发的版本太多，
• 我们的SDK内容很多，文档使用word编写，有40多页，不同版本文档调整的内容不易比对。

由于以上的问题，经常出现：

• 游戏更新版本以后没有同步使用新版本的文档，无法同步更新我们已经修正的文档错误或者新增的版本内容
• 或者由于文档比对太过麻烦和版本太多，开发修改文档错误以后比较难同步修改到其余版本
• 我们的SDK还要支持多语言，由于是word，外包翻译的时候比较难翻译和校对

我们做过的尝试

为了解决这个问题，MSDK团队早期尝试过

• 使用wiki

然而由于wiki的语法太过复杂，编辑的时间成本很高，所以最终还是没能坚持。

• 只提供文档下载地址 下载地址只有我们最新的文档。这样文档online化，但是还不如将文档同步放在版本包。因为这样开发商下载到一次以后就再也不会更新了……

文档online化总要解决，不然上面的问题会一直存在。为了让伟大的开发哥哥们不受困于wiki，最后在github终于找到了神器。

• mdwiki 一个基于bootstrap的，使用markdown编辑内容的js wiki框架。

建议的解决方案

1. online：使用在线文档可以避免很多因为文档不及时替换引起的问题。而这也是我们前期关于接入咨询最多的问题。当然online也是一把双刃剑，带来的问题就是你的文档要支持所有的版本。所以如果有接口再某些版本发生变化，一定要描述的很清楚。
2. markdown：markdown的优势是无法用语言形容的。（附上一个自己写的Markdown的介绍点击查看）。使用Markdown可以大大提高开发者的开发效率。

• 分模块：如果你的SDK够大，建议最好是按照模块来写文档。之前我们的API文档有40多页，从头到尾过一遍就要很久，更不要说比对内容……

文档应该包含的内容

• 流程相关： 商业的接入流程：例如怎么签订合约、怎么申请或者获取APPID、对于有权限的接口怎么申请权限等流程。
• SDK介绍相关： SDK介绍：介绍SDK的能力、包括的模块、名词解释、SDK下载地址、版本历史等内容 接入指引：主要介绍开发者从下载完SDK到将SDK合入自己工程的工作。包括SDK包内容介绍、SDK的架构的简单介绍、开发者接入SDK、更新SDK的操作指引、打包的混淆规则等内容。 API文档：按照模块区分介绍对应模块API的使用方法。建议包含模块介绍、模块接入需要修改的配置、每个API的说明（包括使用场景、接口声明、调用事例、异常处理、注意事项等）、模块接入的FAQ以及一些常见问题的定位方法。其中需要有一个模块是提供一些SDK的基础方法，例如获取SDK的版本号等功能。（在实际中我们发现游戏有时候还是不够熟悉整个模块的接入方法，因此对于具体的模块，我们还会提供整个模块的推荐用法。） 性能说明：主要是介绍SDK的一些测试指标，例如SDK包的大小，运行时对内存、CPU的占用等性能数据。