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.
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.
The Campaign Monitor API documentation is at http://www.campaignmonitor.com/api.
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:
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.
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.
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.)
The Android developer documentation is at http://developer.android.com/index.html.
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.
- One-stop-shop for everything related to development.
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.