Ask ten teams what documentation is for and most will say some version of ‘to describe how the product works’. That answer is the root of nearly every documentation failure you will ever see. Great documentation is not a description of your product — it is a tool that helps a specific person complete a specific task. A feature list tells the reader what exists; documentation changes what the reader can do. Hold that distinction in your head for the rest of this course, because everything else is downstream of it.
The difference is not academic. A page written as a tour of the settings screen and a page written to help someone ‘turn on two-factor authentication for their whole team’ can contain the same facts and yet only one of them is useful. The first leaves the reader to assemble the steps themselves; the second does the assembling for them. That assembling — turning ‘what exists’ into ‘how you get your job done’ — is the entire value you add.
Name the reader and the job before you write
Before a single sentence, answer two questions out loud: who is this page for, and what are they trying to finish? A page written for ‘everyone’ helps no one, because it cannot make the assumptions that make writing clear. A page written for ‘a backend engineer wiring up their first webhook’ practically drafts itself: you know what they already understand, what they are afraid of, and what ‘done’ looks like for them.
Here are two headings for the same feature. Which is documentation, and which is a tour?
- A: ‘The Notifications settings panel’
- B: ‘Send yourself a test alert’
B is documentation: it names a task the reader wants to finish and promises a verifiable result. A describes a screen and leaves the reader to work out what to do with it. Whenever you catch yourself writing an A, ask ‘what is the reader trying to do here?’ and rewrite the heading as that.
The three jobs documentation does for the business
Documentation is not a cost centre or a nicety; done well it is one of the highest-leverage assets your team owns. It pays back in three concrete ways:
- It reduces support load. Every question your docs answer clearly is a support ticket that never gets filed. A good docs page is the cheapest, most scalable support engineer you will ever ‘hire’ — it answers the same question ten thousand times without tiring.
- It shortens time-to-first-success. The faster a new user reaches their first real win, the more likely they are to stick. Documentation is a core part of product activation, not a footnote to it — for many developer products, the docs are the onboarding.
- It builds trust. Clear, correct, current docs signal that the product behind them is well made. Stale or sloppy docs signal the opposite, and readers extend that judgement to your code and your company. Documentation is a public statement about how much you respect your users’ time.
When documentation is treated as a box to tick at the end of a release, all three quietly break at once, and you pay for it in a currency that is hard to trace back to the cause: churn, tickets, and deals that stall because an evaluator couldn’t find an answer at 11pm and moved on to a competitor whose docs were better.
The cost of ‘we’ll document it later’
‘Later’ is where documentation goes to die, because by then the person who understood the feature has moved on, the edge cases have been forgotten, and the pressure of the next release has arrived. The cheapest time to write a doc is when the feature is fresh in someone’s head. The most expensive time is after a customer has already hit the gap and filed the ticket — now you pay for the support interaction and the doc.
Think about your own product’s docs and answer honestly:
- Could a brand-new user reach their first success using only the docs, with no help from you?
- When a support ticket comes in, do you routinely think ‘that should have been in the docs’?
- If a stranger read your docs, would they conclude the product is carefully made?
A ‘no’ to any of these is not a failing — it’s a map. Each one points at exactly the work that will pay back fastest.
In the age of AI
Large language models can now draft a fluent paragraph of documentation in seconds. It is tempting to conclude the craft is obsolete. The opposite is true: AI has automated the easy part (producing prose) and left the hard part entirely to you (deciding what deserves to exist, judging whether the draft is actually correct, and shaping it around a real task). A model will happily generate a confident, beautifully-formatted page describing an endpoint that behaves differently from what it says. It has no idea who your reader is or what they are trying to finish.
So the skill this course builds is more valuable in the age of AI, not less — because the bottleneck has moved from typing to judgement, and judgement is exactly what a model cannot supply. Throughout, we return to one organising idea: different reader needs require different kinds of documentation. Confusing those kinds is the single most common reason docs feel frustrating, and it’s what the next two lessons put right.
Answer, then press Check. Explanations appear after.
True / FalseGreat documentation is primarily a complete description of every product feature.
Choose oneWhich is NOT one of the three business jobs of documentation?