A developer hits the authentication endpoint for the first time and gets a 401 response. The error body says “Unauthorized.” The docs say the endpoint requires a Bearer token, which the developer has already included. The docs don’t mention that the token needs to be refreshed after 15 minutes, or that this particular endpoint only accepts tokens scoped for write access. That information exists somewhere, probably in a GitHub issue from two years ago. The developer spends an hour finding it.
That’s not a bug. That’s a documentation failure dressed up as a product problem.
API documentation has specific requirements that general documentation doesn’t. Users come to it with a concrete goal: make this request work. They’re not reading for context or background. They want to know exactly what to send, exactly what to expect back, and exactly what to do when something goes wrong.
That means every endpoint needs real request examples, not placeholder values. “your-api-key-here” in a curl example doesn’t help anyone. Real examples, using the actual parameter names with realistic values, show users the shape of a valid request. Response examples matter just as much: what does a successful response look like? What fields appear in an error? If an error code appears, what does it mean in practice, and what should the developer do about it?
A working quickstart is not a nice-to-have. It’s the difference between a developer who integrates your API and a developer who doesn’t. The quickstart should get a developer to their first successful API call in under ten minutes, assuming a clean environment. If it takes longer than that, you will lose the developers who are evaluating whether your API is worth their time.
The benchmark that everyone in developer tools references is Stripe. Their documentation at stripe.com/docs uses a three-column layout: navigation on the left, content in the middle, and live code examples on the right in the language you’ve selected. The code isn’t generic pseudocode; it’s the actual request you’d make, in your language, with real field names. You don’t have to context-switch between reading and building.
For anyone who wants to learn how to write API documentation systematically, Tom Johnson’s course at idratherbewriting.com/learnapidoc/ is the best free resource available. It covers everything from OpenAPI spec to writing conceptual overviews to documenting authentication, and it’s written for both technical writers and developers who’ve found themselves responsible for their team’s API docs.
One thing worth saying clearly: the OpenAPI spec is not documentation. It’s a machine-readable description of an API’s surface. A well-maintained OpenAPI spec helps generate reference pages and enables tooling, but a developer reading auto-generated spec output without narrative context, without examples, without error explanations, is still missing most of what they need. The spec is the skeleton. Documentation is the rest.
API docs fail when they describe what the API does in theory without showing what it does in practice. Close that gap and you close most of the support tickets.