终端开发

使用Android Studio开发可独立运行(runnable)混淆过的Jar程序 Android安装包精简系列之资源精简 Android安装包精简系列之图片优化 Android安装包精简系列之为什么要优化精简安装包 Android安装包精简系列(总纲) Android安装包精简系列之图标转字体 gradle相关资料汇总 Android编译常见错误解决 Android编译编译速度提升 终端基于gradle的开源项目运行环境配置指引 制作终端产品演示的gif 一个关于APK Signature Scheme v2签名的神奇bug定位经历 如何随apk一起打包并使用SQLite SDK热更之gradle插件(如何在SDK代码中自动插桩及如何生成补丁包) 关于Android的APK Signature Scheme v2签名相关的资料汇总 封装HttpURLConnection实现的简单的网络请求库 一款基于Java环境的读取应用包名、签名、是否V2签名等基本信息的工具 Android的APK Signature Scheme v2签名及一款基于Java环境的校验工具介绍 如何使用Eclipse开发可执行Jar程序,并生成混淆过的jar程序 Android 相关的学习资料整理(持续更新) macOS(Sierra 10.12)上Android源码(AOSP)的下载、编译与导入到Android Studio Google也看不下去被玩坏的悬浮窗了么? Android开发常用工具资源 SDK热更系列之概述(持续整理编辑中~) SDK热更系列之SDKHotfix待优化点 Android 终端开发相关的一些神图(持续更新) SDK热更系列之Demo项目介绍概述 SDK热更系列之Demo体验方法 SDK热更系列之如何获取应用在当前设备上的so对应的指令集 Gradle Android插件使用的中那些特别注意的点 Experimental Plugin User Guide(From Android Tools Project Site) 基于Android Studio使用gradle构建包含jni以及so的构建实例 基于Instrumentation框架的自动化测试 - Android自动化测试系列(四) Instrumentation框架介绍-Android自动化测试系列(三) 关于终端设备的设备唯一性的那些事之MAC地址 关于终端设备的设备唯一性的那些事之IMEI Android 检查应用是否有root权限 ant常见错误解决方案 Gradle介绍 iMac上Android Studio 相关设置及常见问题 再说adb 再看Android官方文档之分享 再看Android官方文档之Fragment&数据保存 再看Android官方文档之Activity&Intent 再看Android官方文档之ActionBar和兼容性 adb shell input(Android模拟输入)简单总结 再看Android官方文档之建立第一个APP Android开发调试常用工具 ANR(网络资料整理) Java参数引用传递引发的惨案(又一次Java的String的“非对象”特性的踩坑经历) android.view.WindowManager$BadTokenException,Unable to add window Android签名校验机制(数字证书) Robotium二三事-Android自动化测试系列(二) Robotium介绍-Android自动化测试系列(一) Android开发中遇到的那些坑 Eclipse使用中部分经验总结 Android中关于Nativa编译(NDK、JNI)的一些问题 Android简单实现的多线程下载模块 Android内存耗用之VSS/RSS/PSS/USS adb Advanced Command URL编码中的空格(编码以后变为+) Android MD5后 bye数组转化为Hex字符串的坑(记一次为女神排忧解难的经历) Android学习之路 adb Base Command Android Log的那些坑…………

标签

android 46

Android编译常见错误解决 一个关于APK Signature Scheme v2签名的神奇bug定位经历 关于Android的APK Signature Scheme v2签名相关的资料汇总 封装HttpURLConnection实现的简单的网络请求库 一款基于Java环境的读取应用包名、签名、是否V2签名等基本信息的工具 Android的APK Signature Scheme v2签名及一款基于Java环境的校验工具介绍 如何使用Eclipse开发可执行Jar程序,并生成混淆过的jar程序 Android 相关的学习资料整理(持续更新) macOS(Sierra 10.12)上Android源码(AOSP)的下载、编译与导入到Android Studio Android开发常用命令备忘 Google也看不下去被玩坏的悬浮窗了么? Android开发常用工具资源 Android 终端开发相关的一些神图(持续更新) Gradle Android插件使用的中那些特别注意的点 Experimental Plugin User Guide(From Android Tools Project Site) iMac(OS X)搭建私有maven仓库,提供Nexus Responsitory镜像 基于Android Studio使用gradle构建包含jni以及so的构建实例 基于Instrumentation框架的自动化测试 - Android自动化测试系列(四) Instrumentation框架介绍-Android自动化测试系列(三) 关于终端设备的设备唯一性的那些事之MAC地址 关于终端设备的设备唯一性的那些事之IMEI Android 检查应用是否有root权限 iMac(OS X)El Capitan 更新遇到的那些坑 ant常见错误解决方案 Gradle介绍 iMac上Android Studio 相关设置及常见问题 再说adb 再看Android官方文档之分享 再看Android官方文档之Fragment&数据保存 再看Android官方文档之Activity&Intent 再看Android官方文档之ActionBar和兼容性 adb shell input(Android模拟输入)简单总结 再看Android官方文档之建立第一个APP Android开发调试常用工具 ANR(网络资料整理) Java参数引用传递引发的惨案(又一次Java的String的“非对象”特性的踩坑经历) android.view.WindowManager$BadTokenException,Unable to add window Android签名校验机制(数字证书) Eclipse使用中部分经验总结 Android内存耗用之VSS/RSS/PSS/USS adb Advanced Command URL编码中的空格(编码以后变为+) Android MD5后 bye数组转化为Hex字符串的坑(记一次为女神排忧解难的经历) Android学习之路 adb Base Command Android Log的那些坑…………

SDK开发经验之文档

2015年05月19日

为什么要有

关于为什么要有文档,觉得所有人应该都懂,想总结一下发现总结不了,于是就去百度和知乎了一下。附上知乎链接: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的占用等性能数据。



PS:我的博客即将搬运同步至腾讯云+社区,邀请大家一同入驻:https://cloud.tencent.com/developer/support-plan?invite_code=10zhijuy24v4f

赞赏

取消
微信扫一扫,赞赏子勰
扫码支持
屌丝程序猿,鸡血攻城狮!努力学技术,潜心做精品!