Great API Documentation Seen As Key To API Success

Romin Irani, February 27th, 2012

Comments(2)

We list over 5000+ APIs now in our directory. The stakes for API Provider are much higher and one of the challenges that they face is to ensure that the first time developer experience with their API is positive and they receive support during this critical period when they actually try out the API. One of the key areas that API Providers can gain developer acceptance is via an area that is often neglected or just provided for the sake of it. The critical piece is called API documentation. This post contains tips from two companies that publish great documentation via the Twilio API and Parse API.

A lot of API providers simply think that mentioning the API reference with methods and parameters via an API reference section on their site is more than enough. That’s a great first step, but if that’s the last step it is going to most likely fail to cut it with developers who have less time and want to get going with your API as quickly as possible.

The first post, Dont Skimp on Documentation, is written by Kevin Burke at the Twilio Engineering Blog. It starts off with a great example of how a code snippet, while it looks perfect on first glance, is saddled with problems that will make a first time user not understand or execute it. It goes on to stress on key points like:

• Users are busy. As a result do not expect them to read all of your documentation. Instead provide short but complete code snippets that they can try out and get running immediately.
• Provide better error messages

Then completely out of the blue, the article focuses on SEO tips for your API documentation. This is because most users come to your site via Google (in Twilio’s case, more than 50%) and they expect that the search result that they click on, will be self contained and have what they are looking for.

The next post titled “Designing Great API Docs” is written by James Yu, founder of Parse.com. Incidently, Parse.com has got slammed by developers after they invited job applicants to apply via their API. The article stresses on the fact that API documentation is as core to the developer experience as the API endpoints themselves. Some of the key points include:

• Provide Layered documentation, which means providing References, Guides, Tutorials, Quick Starts and Samples as part of an overall documentation set.
• If you are providing support for Multiple languages, make sure that code samples are available in all the languages for developers to copy/paste.
• Developers should be able to navigate your documentation easily without resorting to too many clicks. An example, single page guides that contain everything that a developer would want.

Since we are speaking about API documentation, an additional reference is from Pamela Fox, who worked for Google Developer Relations for 4+ years has consolidated her experience into an aptly titled book called Developer Support Handbook. The handbook contains a section on documentation, which was summarized in a guest post from Fox, The Six Pillars of Complete Developer Documentation.

The handbook gives a good list of items that you should have as part of the documentation set. One of the interesting recommendations there is that of a code playground, where the developer can interactively try out the API methods, punch in the parameters and see the request/response data flowing right within the browser. An example is that of the Google Code playground.

Documentation should and must be an area that API providers focus on for their developers. We have a wealth of best practices available now that you should consider when releasing your API. It could make or break the developer experience when they first try out your API. With stellar API documentation, you have every opportunity to make a great first impression on the developer.