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.🙂

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 4 March 2012, in APIs, technical writing and tagged , , , . Bookmark the permalink. 10 Comments.

  1. Thanks Sarah, this is very useful! Finding good API documentation is not easy, this will come in very handy🙂

    BTW, your book is now available in Canada!🙂 (http://www.amazon.ca/Confluence-Tech-Comm-Chocolate-Extraordinaire/dp/1937434001/ref=sr_1_1?ie=UTF8&qid=1330869474&sr=8-1). I can’t wait to read it!

    • Hallo Nathalie
      Thank you very much, it’s great to know the book is available in Canada now too. It’s interesting to see it establishing itself across Amazon! I’d like to know more about how that works.
      Cheers, Sarah

  2. Hi Sarah. I’m a fan of Campaign Monitor also, but here are a few more:

    http://dev.tendrilinc.com/ — built by an ex-collegue after I showed him our REST API Browser

    https://stripe.com/docs/api — very docco like… simple and useful

    • Hallo Rich
      Thanks, those are very shiny. The Tendril Connect docs are awesome. It took me a while to find the table of contents for the Stripe docs. (They’ve called it “Navigation” and it’s a dropdown.) But once I’d got used to it, I liked it.
      Cheers, Sarah

  3. Nice post Sarah. The “good/great/best API/online/REST documentation” question comes up fairly frequently on stackoverflow. Flickr and JQuery up fairly frequently as it does here:

    http://stackoverflow.com/questions/2356567/who-has-great-api-documentation

    I’ve found the discussion on REST API docs really useful in the past:

    http://stackoverflow.com/questions/3622766/best-rest-api-documentation

    (Rich’s RAB is easily as good as Gowalla IMO.)

    Also stackoverflow has discussions about APIs in general.

    http://stackoverflow.com/questions/1515326/what-do-you-consider-good-api-documentation

    This is a fairly substantial thread creating which is very interesting and along the same lines:

    http://stackoverflow.com/questions/2001899/creating-great-api-documentation-tools-and-techniques

  4. What about a user manual like this?

  1. Pingback: Develop in the Cloud - Karl Hakkarainen - What Developers Want on Boxing Day

  2. Pingback: How to become an API technical writer | ffeathers

  3. Pingback: World’s best API documentation – what do you think | ffeathers

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: