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也是一把双刃剑,带来的问题就是你的文档要支持所有的版本。所以如果有接口再某些版本发生变化,一定要描述的很清楚。
  • 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的占用等性能数据。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏编程

开发一款app从PHP到API接口

一、先简单回答两个问题: 1、PHP 可以开发客户端? 答:不可以,因为PHP是脚本语言,是负责完成 B/S架构 或 C/S架构 的S部分,即:服务端的开发。(...

44290
来自专栏ytkah

测试了小程序的内嵌网页总结几点

  11月2日深夜微信团队宣布小程序内嵌页面开放了,很多开发者已经测试了小程序的内嵌网页,他们总结了以下几点: 1、内嵌网页的域名需要在小程序管理后台设置为业务...

35250
来自专栏Rainbond开源「容器云平台」

技术解读Rainbond Service Mesh微服务架构_开源PaaS Rainbond

20420
来自专栏Netkiller

消息队列在使用中的注意事项

消息队列在使用中的注意事项 异步不是万能的,实现异步重要的手段,消息队列在使用中也是有很多注意事项的。 消息队列的瓶颈 消息队列至少有三处容易出现瓶颈,我们一经...

35950
来自专栏匠心独运的博客

过来人的经验,谈谈一致性处理方案—分布式事务(DTS)

传统事务是使用数据库自身的事务属性(ACID),而数据库自身的事务属性是局限于当前实例,不能实现跨库。而对于大型分布式/微服务集群系统中,不仅存在着跨库的事务,...

47040
来自专栏python开发者

"过期不候"--具备生命周期的数据的技术实现方案

"过期不候"--具备生命周期的数据的技术实现方案 1   引言 本文可以作为之前的一个 原理性文章 对应的 技术实现部分 。 此处给出其上文的直达电梯: htt...

24950
来自专栏aCloudDeveloper

vhost:一种 virtio 高性能的后端驱动实现

什么是 vhost vhost 是 virtio 的一种后端实现方案,在 virtio 简介中,我们已经提到 virtio 是一种半虚拟化的实现方案,需要虚拟机...

1.1K60

使用Node.js构建API网关

当微服务架构中的服务被外部的客户端访问时,可以共享有关身份验证和传输的一些常见请求。API网关提供了一个共享层去处理服务协议之间的差异,同时满足特定客户端(像P...

46190
来自专栏开源优测

有那么几张图给大家看看

8410
来自专栏程序员互动联盟

【专业技术】Android如何实现推送?

存在问题: 现在各种实时推送消息不时的在我们手机通知里闪烁,而windowphone搞了那么久在加上,实时消息要求的是实时性。在我们开发中如何掌握这种实时模式呢...

64250

扫码关注云+社区

领取腾讯云代金券