构建完美SDK的10大技巧
英文原文：10 Tips on How to Build the Perfect SDK
这篇博客起源于我一个朋友的咨询，他认为关于写一个好的 SDK，使得别人能够简单地使用方面，现在没有足够的文档。
过去十年来，SDK 使用已经变成了开发生命周期中一个重要的部分。事实上，它是如此常见地被使用并集成到产品中，以至于有人会说开发者需要去获取更多关于框架的知识而不是学习深入的算法知识来提升自我。
这篇博客主要是针对以下朋友，他们想要学习怎样去写最好的 SDK 并为它提供支持文档。一个 SDK 的目标或定位在于它的文档应该是聚焦的和清晰的。如果你发觉文档中的聚焦领域多余一个，考虑分开它吧！
下面是一个列表，我希望能帮你以一种良好的方式去构造一个 SDK，并编写它的文档：
0. 去获知那儿有什么东西
努力查看你的竞争者或公司在相似领域做了什么东西。这会给你一个参考点。拿走你喜欢的方面，改善你不喜欢的方面。
1. 简易
代码—-简单的代码意味着你的客户会发现它易于使用。这就包含与你代码尽可能少的交互方式，例如，只暴露一个接口类；简短的方法签名，例如，少量的输入参数个数，等等。
除了初始化函数以外，它只会出现一次并可能需要一些配置，让你的 SDK 方法的使用尽可能简单。
同样地，努力保持方法签名带有尽可能少的参数。
你可以通过提供默认配置和默认实现类来实现上面的目的，这些能被高级用户来重载修改。
隐藏任何用户不需要使用的类和方法，只有用户必须使用它们才将这些类或方法声明成公有，否则使用局部或私有域。一些开发环境能够使用代码检查和清除来帮助你自动实现上面功能。
文档：让你的文档尽可能简单。有时候这意味着写更多的解释性文字，而另外一些时候又意味着写尽可能少的文字。内联的代码示例经常会有所助益，因为大多数人通过例子来进行学习。
2. 提供一个轻松入门
一个简单的入门方式是那种让一些人在少于 5 分钟内就能使用你代码的方式。这点非常重要，因为用户想要尽可能少的集成时间，更甚者，有时候用户想要去评价你的产品，如果没有一种能力能够简单地做一个实验，他们很可能选择直接踢掉它。
3. 保持它简短化
这部分主要是关于文档的，但是它也与用户能够与 SDK 代码交互的方式相关。考虑到文档，通过提供代码示例和自解释性方法名称和使用默认设置可以实现简短化。
4. 集成
时刻记住，你的用户的开发环境是多种多样的。
例如，如果你正在写一个安卓库，将它集成起来的方式是多样化的，如果你的用户使用含有 gradle 脚本（它需要一个 arr 的史前配置，并会发布到一个偏僻的版本库）的 Android Studio，或者他们使用 Eclipse，这样就需要提供 jar 文件，提供关于如何修改 AndroidManifest.xml 文件的说明文档，以及一个单独的针对 SDK 的 eclipse 工程。
这会影响到你的编译机制，它就是一个史前古物。但是，不要想着头一天就解决所有问题。做些与你第一个客户或你预计的客户最匹配的工作。
5. 简单的工程
在 GitHub 上创建一个最基本的工程，模拟一个客户正使用你的 SDK 的方式。
这会给你的客户展示你的产品是如何满足他们的需求以及与你产品交互最简单的方式。如果你想展示一个更高级的使用方式，在另外一个工程中去展现吧。经常地，你的用户会将这个工程当作他们主要的文档来源来使用，那么，请提供内联的注释语句，并尽可能以自解释的方式写代码吧。
6. 概览
在 GitZHub 工程的 README.md 文件中，开头的文档部分要使用简单的英语去提供关于你的解决方法的一个概览。在这部分，我通常喜欢提供一个示例来解释 SDK 的典型使用方法。如果可能，提供一个简单的图表，因为用户不喜欢读使用手册，这样他们可以很快获知你的 SDK 的优点。
7. 初始化
在 SDK 领域使用约定惯例。
它包含构造器重载，编译模式或者类似的约定。初始化应该有技巧地使用默认配置来保证一个轻松入门。
8. 默认选项
为了保持代码简单和减少配置（请查看“简易”那一节）默认选项是很重要的。你提供的默认选项（不管是配置或实现）都应该展现一种方式，你认为你的大多数用户会如何使用 SDK 的方式。
你可以提供几个方法重载，最简单的签名会缺省调用更高级的方法签名。
9. 发布
- 线下使用不可编辑的格式—-PDF。优势在于你能很简单地创建一个 PDF，在本地 Dropbox 中保存，每当升级时，版本也会自动升级。
- 线上—-你公司的站点。这是一个推荐的方式，然而，每当你升级的时候，它会产生一个麻烦，会有一些 IT 方面的开支。
希望这些指南会对你有所帮助。非常期待你的反馈。
-
译文链接：http://www.codeceo.com/article/10-skills-build-sdk.html
翻译作者：码农网 – civic5216
正文到此结束
热门推荐
相关文章
Loading...
![[HBLOG]公众号](http://www.liuhaihua.cn/img/qrcode_gzh.jpg)
