What developers want

Recently I asked a few super-geeks this question: “What’s your favourite API doc site in the whole wide world?” Here is a short list of the sites mentioned and why the developers like them.

Campaign Monitor

The Campaign Monitor API documentation is at http://www.campaignmonitor.com/api.

Campaign Monitor welcome page

In this case, the developer didn’t tell me why he liked this site. Here’s my assessment of this documentation’s good points:

• Nice welcome page. It tells you what you can do, and links you up with everything you need.
• I love the message it gives to developers: We will help you build awesomeness.
• Good getting started guide.
• Clean, clear reference documentation.

Let’s take a closer look at one of the APIs – the account resource:

Campaign Monitor account API

It’s clean and clear. First comes a short summary of what the API does. Then the guide shows you how to do specific things with that API, such as getting a list of all clients in your account.

Flickr

The Flickr API documentation is at http://www.flickr.com/services/api/. This example shows a page where you can do a real-time test of the authentication API.

Flickr API testing

From the developer who answered my question about why this documentation is good

• Being able to test the API in real time is awesome.
• Note the “useful values” section on the right.

Google

The full list of Google APIs is at http://code.google.com/more/. This example shows the Google Maps JavaScript API.

Google Maps JavaScript API

Why the developer likes this documentation:

• You can easily see what is possible.
• They have a standard formatting for code.
• It is very easy to get started. You can have a working “hello world” in less than 30 minutes.

On top of all that, the docs just look good! (That’s from me, not the developer.)

Android

The Android developer documentation is at http://developer.android.com/index.html.

Android developer documentation

I think that a lot of the appeal is the super-cool appearance of this documentation!

Here are the reasons the developer gave for liking it:

• Gets you started quickly.
• Great introductory videos.
• Outline of overall architecture.
• Examples.
• One-stop-shop for everything related to development.

jQuery

The home page of the jQuery developer documentation is http://api.jquery.com/. The example below comes from the attr() function.

jQuery API documentation

What the developer appreciates in these guides:

• Interesting challenge: The language supports functions that vary in behaviour based on their parameters. In this example, the attr() function supports two different calling modes.
• Documentation supports contributions.
• Good permalinks.

Thank you to the developers who answered my question, which came out of the blue one day! The answers were a great help in designing the new look of our developer documentation home page.