Blog Archives

World’s best API documentation – what do you think

I’m curious to see how things have changed since I last asked this question, back in March 2012: What’s your favourite API documentation, and why?

Part of the reason for asking is that I’ll soon present a session at STC Summit 2014 on API technical writing. I want to give examples of excellent documentation. I have some favourite documentation sets myself, but it’s great to get the opinions of developers and other technical writers too.

So, have at it! :) Please comment on this post.

What’s your favourite API documentation, and why?

I’ll also collect any suggestions that people send via Twitter, Google+, and other channels, and add the links to this post.

OT: This has to be the world’s best bird. Well, it’s my current favourite anyway. This is a Tawny Frogmouth, spotted on an early morning walk. Tawny Frogmouths are night birds, about the size of a large owl (34-52 centimetres). During the day, they pretend to be old tree branches.

A Tawny Frogmouth chilling out

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. :)

Follow

Get every new post delivered to your Inbox.

Join 1,396 other followers

%d bloggers like this: