Don't Panic — API Documentation

An API is a contract: here is what you can ask for, here is what you get back. API documentation is everything that helps a real person turn that contract into a working request without emailing a stranger for help. That "everything" is the whole problem. It is tempting to believe the contract explains itself.

It doesn't, and the evidence is what people fall back on when nobody wrote anything better: a generated endpoint list, straight from the code, plus a support queue full of the questions the list didn't answer. A list of methods and paths names the operations. It does not tell you what permission each one needs, what its parameters actually accept, or how to tell when you've read the last page of a paginated result. Generating that list is nearly free. Everything that makes it usable is not.

The course organizes that "everything" around the reader's situation rather than around the API's own shape, because different readers arrive with different jobs. Someone evaluating the API wants to know if it fits. Someone starting out wants one safe success. Someone already working wants one exact fact, fast.

Four kinds of writing answer those jobs, and each has its own name: a guided first success, task-focused steps for someone who already has context, precise lookup material, and the "why" behind a design choice. Keep them apart and link between them. Collapse them into one page and you've built something that serves nobody well — the Cheatsheet tab lays out which one does which job.

Here's the part that surprises people who assume more automation solves this: an OpenAPI description — the machine-readable file that can generate your reference pages — is a source, not a finished product. It cannot decide what a new evaluator needs to know, write a safe getting-started path, or notice that an example stopped working.

The fix people reach for instead makes it worse, not better. Handing consumers a generated client library so they never touch raw HTTP doesn't remove the documentation burden; it relocates it. Now you're maintaining a wrapper's own method names and failure modes, in every language you shipped one for, on top of the API it wraps — one of several places the Field Notes tab shows the standard advice quietly costing more than it saves.

The second surprise is where failure documentation belongs. It is not a footnote after the happy path. 401, 403, 429, and friends are outcomes just as real as 200, and a reader who only sees the success case learns the failure modes by triggering them in production instead.

From here, the Practice Session turns the reference-page checklist into something you write yourself, against a small scenario with a right answer. The Quiz checks whether the reader-situation model actually stuck.

Don't Panic — API Documentation

Relevant careers