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

相关文章

来自专栏我是攻城师

分布式日志收集之Logstash 笔记(二)

33860
来自专栏大数据智能实战

千万级别以上的地图兴趣点(POI)的快速查找测试

近期,终于有点时间,将之前的地图兴趣点爬虫程序(http://blog.csdn.net/sparkexpert/article/details/5155481...

48980
来自专栏腾讯技术工程官方号的专栏

腾讯云Kafka海量服务自动化运营实践

7.7K50
来自专栏IT技术精选文摘

微信支付商户系统架构背后的故事

PostgreSQL-XC在事务管理系统方案本身有一个明显的缺点,那就是事务管理机制会成为系统的瓶颈,GTM(Global Transaction Manage...

17510
来自专栏云计算

异步数据存储声明

在过去的几年里,NoSQL数据存储的工作让我对应用程序的方向有了一些见解,因为NoSQL成为了主流的数据存储和检索方法,至少对网络和基于云的程序来说是这样的(企...

22590
来自专栏实用工具入门教程

如何部署 R 开发环境

R是一种开源编程语言,专门用于统计计算和图形绘制。R在统计的基础下,被广泛用于开发统计软件和数据分析。R是一种日益流行且可扩展的语言,拥有活跃的社区,为特定的研...

24630
来自专栏Java学习网

网页打开时都发生了什么?我被吓着了

  在浏览器里输入网址或者点击链接,网页打开了……这是我们上网时再普通不过的一幕,但是如此简单的表象背后,却隐藏着无比复杂的技术流程。想涨涨知识吗?往下看吧。 ...

37960
来自专栏杨建荣的学习笔记

给自己写的程序挑毛病(r12笔记第68天)

前几那天写了一个Java程序模拟生产者消费者,当时写完还感觉不错,但是这几天再看的时候发现还是有很多的不足之处,给别人挑毛病不大好意思,尺度拿捏不好还容易...

36850
来自专栏微信终端开发团队的专栏

微信自研生产级paxos类库PhxPaxos实现原理介绍

微信重磅开源生产级paxos类库PhxPaxos,本文用科普的口吻向大家介绍PhxPaxos背后的实现原理以及一些有意思的细节。 开源地址:https://g...

33170
来自专栏非著名程序员

推荐几个适合新人上手的Python项目

10420

扫码关注云+社区

领取腾讯云代金券