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