Some weeks ago I watched a speech by Jacob Kaplan-Moss, one of the lead developers at Django, about writing good documentation. Kaplan-Moss have some very good key points which we have had in mind when structuring our new developer platform. I’m not going to summarize his speech in writing, instead I will explain how we’ve been thinking when developing our new platform.
Different user needs
First of all, haven’t we all had times when we’ve read or heard about some cool new product, API or library which just sound awesome but after spending hours of trying to figure out how it’s supposed to be used just dropped it and gone for something else. After all, most of the new stuff we sign up to is because of the buzz and spontaneous raid to try the newest things. Also there are those cases where it’s very easy to get started but that’s it, there is no way of getting deeper knowledge without digging into the source code. Last but not least – troubleshooting. It’s not a matter of ‘if’ rather than a matter of ‘when’ a developer encounter problems there must be an explanation of how to solve it, or at least a way for the user to get some help. Lets take a look at our different sections and thoughts for each section.
First contact – Demo
The absolute first contact developers have with Saplo API is our demo site. Here we want to be able to give a fast demonstration of how Saplo works in its simplest way. Paste a text into the input box and get related texts and tags to the submitted text. We know that we can improve our demo site in many ways and we will, but hopefully it gives you a quick and easy understanding of what Saplo can do.
If you have decided to give Saplo a try, we will work as hard as we can to help you get going. First of, libraries. We will try to provide libraries for as many languages as requested. We are far from experts on all of the languages out there, but we hope that we can cover some groundwork and that you want to help us improve the libraries over time. From release day we will have libraries for at least PHP, Python and Java. To get you going we have put effort into our Getting Started Guide with simple explanation and examples to run. Hopefully this will give you the help it takes to get hooked.
As the title says, we will have a tutorial section where we step-by-step will guide you through different use cases. Perhaps in the future this can be filled with users own tutorials and experiences.
When a user is familiar with the API, its structure and basics, then it’s time to extend the experience. The Topics is the place you go to when you want to get even more out of the API. This is the place where we explain how different resources works and how they can be used to achieve greater things. Ideas of products and services that can be built using Saplo API is put here.
References & Methods
Of course an API need to have all its methods documented. As the API grow, methods will be added and then it’s even more important that it is easy to find and understand the structure of the API. In the methods section we list all available methods with its associated request and response parameters. We also provide example code for each method and if needed any important notes.
As we all know, sooner or later people will get stuck and when they do they want answers. In our troubleshooting section you will find answers to the problems, why it happens and how to solve it. If you’re getting an error code or an unexpected result, then this is where you should find the answer. This section will continuously be filled with information as we get new questions from users. Let us hope you never end up in this section but if you do we’ll do our best to keep your visit short and effective.
This was a short walk through on how our new developer platform is structured. Stay tuned for its release. Many thanks to Jacob Kaplan-Moss for his inspiring speech on the subject. Watch his speech on writing great documentation if you haven’t.