A new developer given API credentials and a link to a full reference document — every endpoint, every field, every enum value, alphabetized — does not read it. They open the reference in one tab, open a second tab to search for the one thing they're trying to do right now, and never come back to read the parts they haven't needed yet. A reference document optimized for completeness is optimized for the 2% of visits that are a working engineer doing an exhaustive lookup of a field they half-remember, and it actively fails the other 98%: someone trying to make their first successful call, or someone trying to fix one specific error they just hit.
Good API documentation is not one document doing one job — it is several different kinds of content, each answering a different question, that happen to live under one navigation menu. A newcomer needs a path that gets them to a working call in minutes. Someone building a real integration needs task-focused guides for specific goals ("how to paginate through a large result set", "how to handle a webhook retry"). Someone already fluent in the API, mid-debugging-session, needs the exhaustive reference to check one exact field's type. Treating all three as the same document, written the same way, for the same reader, is why so much documentation gets written once and never actually used by anyone doing real work.
This lesson treats documentation as part of the API's design surface, not an afterthought written once the "real" work of building the API is done — because a consumer's actual experience of an API is overwhelmingly mediated by its documentation, not by the specification file they will likely never open directly.
Analogy🏏Cricket
🏏 Think of it like cricket: A team's video-analysis department produces three genuinely different products from the same raw match footage, for three genuinely different audiences. A short highlights reel gets a new signing quickly up to speed on the team's recent form, without needing to watch four full days of a Test match. A specific tactical breakdown — "here's exactly how we bowled to this particular batter last time" — gets the bowling attack ready for one specific upcoming task. And the complete, ball-by-ball archive stays available for the analyst who needs to check one exact delivery from a match eight months ago. Nobody hands the new signing the complete ball-by-ball archive and calls it onboarding, and nobody hands the analyst only the highlights reel and expects them to find one specific delivery in it. Just as the video department builds three different products because it has three different jobs to do, not one job done three times, good API documentation builds a quickstart, task guides, and a reference because each answers a different question a real consumer actually has. Just as using the wrong product for the job wastes the viewer's time, no matter how well-made the product is, using the wrong documentation type for the reader's actual question wastes the reader's time, no matter how thoroughly the reference was written. The insight is that documentation quality is measured by whether the right content reached the reader with the right question, not by how much content exists in total.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.