Writing documentation is one of those things that is dreaded by many developers. It takes a lot of effort and time to get right. And too often, people take shortcuts. This is sad, because well designed documentation is the key to getting people excited about your project, whether it's open source or a developer focused product.
In fact, I argue that the most important piece of UX for a developer product isn't the homepage or the sign up process or the SDK download. It's the API documentation! Who cares if your product is the most powerful thing in the world if no one understands how to use it.
If you're a making a developer focused product, the documentation is as core to the user experience as the endpoints themselves.
I've seen far too many projects that simply dump you to a GitHub page with a two-liner readme. The most successful API docs are carefully crafted with love. Here at Parse, we devote ourselves to this art.
So, what elements go into making great API documentation?
Documentation is a Layered Beast
Your documentation shouldn't just be a plain listing of endpoints with their parameters. Documentation is a whole ecosystem of content that aims to teach users how to interact with your API. At the very least, you should have these components:
- Reference: This is the listing of all the functionality in excruciating detail. This includes all datatype and function specs. Your advanced developers will leave this open in a tab all day long.
- Guides: This is somewhere between the reference and tutorials. It should be like your reference with prose that explains how to use your API.
- Tutorials: These teach your users specific things that they can do with your API, and are usually tightly focused on just a few pieces of functionality. Bonus points if you include working sample code.
At Parse, we have all three of these components, and we're currently working on fleshing out more tutorials.
Another good example is Stripe's API, which has an awesome hybrid guide and reference and also a cadre of great tutorials. GitHub's reference API is also very well designed.
Remove Abstractions with Examples
You could argue that your API is one big abstraction, and that's kind of the point. However, when teaching developers, try to remove as many abstractions as possible.
Liberally sprinkle real world examples throughout your documentation. No developer will ever complain that there are too many examples. They dramatically reduce the time for developers to understand your product. In fact, we even have example code right on our homepage.
Minimize Clicking
It's no secret that developers hate to click. Don't spread your documentation onto a million different pages. Keep related topics close to each other on the same page.
We're big fans of long single page guides that let users see the big picture with the ability to easily zoom into the details with a persistent navigation bar. This has the great side effect that users can search all the content with an in-page browser search.
A great example of this is the Backbone.js documentation, which has everything at your fingertips.
Include a Gentle Quickstart
The hardest part of adopting a new API is right at the beginning, where the learning curve is steep and the developer is exposed to complicated new ideas. The solution to this is to introduce the API with a quickstart guide.
The goal of the quickstart is to walk the user through the minimal steps needed to do the smallest thing possible in your API. Nothing more. Once a user has done this, they're ready to move on to the more advanced concepts.
For example, our quickstart guide has the user download our SDKs and then save one object to our platform. We even have a button that lets users test whether they've done this correctly. This gives them the confidence to move on and learn the rest of our platform.
Use Multiple Languages
We live in a polyglot world. If appropriate, try to list examples for multiple languages that your API supports, most likely via client libraries. Learning a new API is hard enough without having to parse unfamiliar languages.
MailGun's API does a great job of this by letting developers choose between curl, Ruby, Python, Java, C#, and PHP for the examples in a global menu.
You Can Never Over-communicate Edge Cases
The worst thing is to be developing with an API only to discover an error state that isn't documented. In situations like this, it can be unclear if the error is in your code, or in your understanding of the API.
Your reference should include every edge case and every assumption that is made, either implicitly or explicitly. Spending a few minutes doing this can save hours of your user's collective time.
Sample Applications
At the end of the day, developers want to see the big picture. And the best way to show that is with working sample applications. I find that application code is the best way to communicate how everything in your API ties together and how it integrates with other systems.
A great example of this is sample code in Apple's iOS Developer Library, which has an exhaustive selection of sample iOS apps organized by topic.
Add Personality
Reading API documentation isn't exactly a thrilling roller coaster ride. But, you can at least add some personality and fun into your writing. Surprise your reader with funny examples and variable names other than foo.
This will at least prevent them from falling asleep.
Conclusion
The way to a developer's heart is great documentation. And, great documentation requires a lot of investment. But, this investment is well worth it, and is just as important for a developer product as the API itself.
The other half of this is designing a great API in the first place. But, that will be the topic of another post.
Source:http://blog.parse.com/2012/01/11/designing-great-api-docs/
