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 条评论
登录 后参与评论

相关文章

来自专栏云计算

微服务的模式 - 同步与异步

微服务是一种架构范例。在这种架构中,多个小型独立组件协同工作,从而构成一个系统。尽管它的操作复杂性较高,但这种范式已经被迅速采用。这是因为它有助于...

1.1K4
来自专栏CSDN技术头条

携程开源Redis多数据中心解决方案XPipe

Redis在携程内部得到了广泛的使用,根据客户端数据统计,整个携程全部Redis的读写请求在每秒200W,其中写请求约每秒10W,很多业务甚至会将Redis当成...

3959

使用IBM云功能构建无服务器应用程序

在Serverlessconf一文中,IBM宣布了IBM云服务器的一项新功能(作为IBM Research预览版)。使用新的工具Composer,可以创建包含多...

2109
来自专栏大葡萄元元

开发一款app从PHP到API接口

答:不可以,因为PHP是脚本语言,是负责完成 B/S架构 或 C/S架构 的S部分,即:服务端的开发。(别去纠结 GTK、WinBinder)

2801
来自专栏开源优测

有那么几张图给大家看看

661
来自专栏IT笔记

Lepus搭建企业级数据库全方位监控系统

Lepus(天兔)数据库企业监控系统是一套由专业DBA针对互联网企业开发的一款专业、强大的企业数据库监控管理系统,企业通过Lepus可以对数据库的实时健康和各种...

1305
来自专栏aCloudDeveloper

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

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

6966
来自专栏Java编程技术

分布式事务- TCC编程式模式

严格遵守ACID的分布式事务我们称为刚性事务,而遵循BASE理论(基本可用:在故障出现时保证核心功能可用,软状态:允许中间状态出现,最终一致性:不要求分布式事务...

1193
来自专栏BestSDK

一提交代码系统就崩溃? 给你8个避免此尴尬的技巧

当一群人作为一个整体同时进行一个程序的编写时,每个个体都会面临两方面的权衡: ●个人部分的实现——你需要保证你负责的代码部分可以正常运行; ● 整体部分的实现—...

3687
来自专栏hotqin888的专栏

MeritMS与Bentley Project Wise对比校审流程

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/hotqin888/article/det...

1691

扫码关注云+社区