API documentation autogenerators can give a misleading sense of security. It’s too easy now to produce status quo or only adequate documentation. Creating great documentation takes this to a new level, and requires new insights.



The goal is to produce a developer experience that exceeds anyone else’s documentation. That definition is that we provide all the information developers need so that there is no doubt in their minds that what they’re doing is correct, or leaves no doubt what to do next. This is more than writing descriptions about a call. It’s about anticipating their questions, making everything copy and paste, providing examples, sample projects, getting started documents, and leading them to the next place.



It’s all about coding.

We’re entering their world, and we have to speak their vernacular.

We’re here for their convenience, not yours. It’s about anything that saves them time. For instance, provide the code samples.

cURL is not programming cURL is a testing tool, and not even the best one. It’s also not how they’re going to make the call.

You’re never done writing. Review constantly. First, you’re going to learn more each day, so add that material. Second, go back in a week, a month, or three months and review material. You’ll it through the eyes of some reading it for the first time.

Examples are everything. It says it all: Examples are everything. Make examples copy and paste, place them prominently, and vary the examples.

Links don’t solve anything Link to as little as possible. Inline and reuse as much as possible. Linking wastes developer’s time and just annoys them.

If it’s not already broken, then break it. Your tool is broken if it doesn’t do exactly what you want it to do. Yes, for writers is every tool we have. So complain about it to manufactures, and to forums. It’s the only way to we’re going to get change.