As an application developer I get to use many third party code to integrate it into my current project. I want to share a checklist of things a user of an SDK really appreciates.
This is the most important part of any SDK, be it open source or closed source. Users don’t need to understand your code, or learn by themselves how to use your APIs. Maintaining documentation is a big part of maintaining an SDK, and it goes far beyond documenting the code.
Really, this is very important and lacking on many commercial SDKs. Please include examples, rationale and FAQ.
Don’t get it? Just some examples of great additional documentation:
Please, open source your SDK
There’s nothing more annonying than encountering bugs or unexpected behaviour and having to skim through logs, documentation and trial and error tests. This can happen anytime when using unfamiliar APIs, and having the source to understand what goes wrong is the first big benefit of open source SDKs. Furthermore, if you accept contributions from the community, you might get some developers helping with debugging and fixing issues.
Having open issue discussions help with questions and faster communication. A good example is projects on Github. See an example of Snowplow devs just guiding me over my confusion.
Surely your business model is not dependant on you not publishing the source code that interacts with your platform?
Any developer including third party code in an application is assuming the quality of your code into theirs. They also have the final accountability for the end users, who don’t care where a bug or crash is coming from. Good engineering practice will make users of your SDK wary of changes you introduce, so a changelog is very important to let them know what changed.
And please, don’t just add stability improvements.
Version migration documentation
More documentation! This is very special and also very important. If you maintain an SDK for long enough you’re necessarily going to need to break APIs. It’s at this time that users of your SDK will suffer the most, because an application developer doesn’t track your development on a day to day basis. It’s very crucial for the happiness of your users that you provide good examples of how to transition to new APIs with the least effort possible. I like this migration guide from Snowplow a lot.
Your SDK is not the only one
Many examples you can find are very naive in terms of what the host application code contains. Don’t expect that the user of the SDK will be using your code exclusively. Compare these two getting started examples from very respectable SDKs:
Facebook. From their docs.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Branch. From their docs.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Both SDKs provide you with a naive example without explaining what the return results are, and the eventuality of an application doing more work than actually using their SDK. Seems a very contrived example but consider that a clever engineer will not copy-paste your example code, but integrate it into their application where it fits best.