专栏首页子勰随笔SDK开发经验之Demo

SDK开发经验之Demo

为什么要有

好吧发现这个和要说为什么文档要有一样也好蛋疼。简单说一下吧。

  1. 程序猿都是艺术家,你提供的接口被使用的方法只有你想不到的,没有他们做不到的,没有一个事例他们容易用错。
  • 好吧,其实关键是很多程序猿都很懒,他们想你都有接口API了,那怎么调用的也写一下么,我就直接拷过来改改参数就好了。所以他们就会说你们的SDK不好接入,你们要优化,要有调用事例,胳膊拧不过大腿,最终就都有了。
  • 好吧,其实还有程序猿们都很有怀疑精神,虽然有文档,他们也是按照文档做的,可是他们总不放心,因此demo显得就很重要,他有可以参考的对象了。
  • 文档并不能非常整体的、清晰的展现你的SDK的整个系统和调用方式。
  • 对于刚接触你SDK的人,你用一个demo来介绍SDK的功能会比文档形象更多,也更易理解。一图胜千言,一demo胜千图应该也是可以的。

最后,再把知乎上关于文档别人说的这一段描述修改下,发现更加恰当了(点击前往知乎):

仅仅通过他人的口述、视频、文档往往无法完整的了解到SDK的接口的所有的作用,好比盲人摸象,你对它的认知、印象、经验将完完全全从他人所提供的教程中继承而来。而Demo能够全面地介绍出它所包含的所有内容,能够辅助你学习如何“使用”它。

展现形式

  • 最好是独立的包含完整功能的APK应用:如果只是部分模块或者部分接口的事例代码,那么文档足矣,根本无需Demo
  • 虽然Demo的主要功能是为了协助用户了解SDK的功能,但是也别太丑了:之前我们的Demo丑到我都看厌了,不好意思拿出手。
  • Demo中功能演示最好也分模块来展示,而不是把所有的功能揉在一起:我们的SDK有几十个接口,Demo最开始所有的功能用一个自动生成的ListView放在一起,加上配色的问题,每次测试某个功能都要找呀找,找不到我要的小伙伴。
  • 既然都Demo了,大部分活都做了就多做一点,在展示某个功能的时候,能把调哪个接口、什么效果、注意事项等都简单说明下。别整个Demo就是把功能跑一遍,要看某个功能是调哪个接口,调用要注意什么还要去看代码和文档。(最开始我们就是这么做的)

注意要点

  1. Demo对接口的使用方法一定要和文档要求或者推荐的一致。本来文档加Demo的目的是减少接入咨询的工作量。结果你这俩都不一样,全来问了,还不如没有呢,不是自己打自己脸么(很不幸,我们被打过)。
  2. Demo中与接口调用事例无关的代码要尽可能的少虽然说不能太丑,但是也不能太花里胡哨,如果想花里胡哨,那部分代码最好不要和接口的调用事例的代码柔和在一起。不然开发看懂你的demo的时间他都接完了。

暂时就写这么多,之前感觉挺难写的,发现逗比起来就好写多了,暂时这么多,后续想起来慢慢补充。

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

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 基于mdwiki使用Markdown实现的wiki

    子勰
  • SDK开发经验之文档

    子勰
  • 开发中常用的一些Chrome插件介绍

    子勰
  • Bayesian Personalized Ranking 算法解析及Python实现

    最早主要是利用词频、逆文档频率和文档长度这几个因子来人工拟合排序公式。因为考虑因素不多,由人工进行公式拟合是完全可行的,此时机器学习并不能派上很大用场,因为机器...

    Bo_hemian
  • 在线文档的抗“疫”战事

    很多公司每天都要召开在线会议。如果没有在线文档的支持,在线会议的“打开方式”可能是这样的:组织者在会议开始前将会议材料发给参会者,大家各自打开材料结合演讲者的讲...

    罗超频道
  • Solr查询处理简介

    所有与solr核心服务有关的交互,如查询处理,都是通过HTTP请求执行的。填写查询表单之后,创建一个HTTP Get请求并发送给Solr。

    栋先生
  • 一个Sqrt函数引发的血案

    好吧,我承认我标题党了,不过既然你来了,就认真看下去吧,保证你有收获。 我们平时经常会有一些数据运算的操作,需要调用sqrt,exp,abs等函数,那么时候你...

    范蠡
  • 如何编写出优秀软件

    如何编写出优秀软件   软件必须是自由的   优秀软件是自由软件。我将避免使用“开源”,因为它根本没有包含社会层面,它和技术本身同等重要。你可以从这里了解更多...

    用户1289394
  • 资源 | 神经网络调试手册:从数据集与神经网络说起

    选自Hackernoon 作者:Andrey Nikishaev 机器之心编译 参与:黄小天 近日,hackernoon 上出现了一篇题为《How to deb...

    机器之心
  • 下一代网络钓鱼技术——滥用Azure信息保护功能

    在这篇文章中,我们将从攻击者的角度介绍如何使用Azure信息保护(Azure Information Protection,AIP)来改进网络钓鱼技术。这个想法...

    周俊辉

扫码关注云+社区

领取腾讯云代金券