Every strong doc set begins with a step most people skip: two lists, written down before you touch a single page. The first is your readers. The second is the tasks each reader needs to complete. Skip this and you will, without noticing, end up documenting your architecture instead of your users’ goals — technically accurate, and practically useless.
This lesson is the most important planning habit in the whole craft. It is also the one AI cannot do for you, because it depends on knowing your actual users and your product’s real edges. Get it right and everything downstream — structure, headings, even the AI drafts you generate later — falls into place.
Step one: list your readers
Name the distinct people who arrive at your docs, and note what each already knows. For a typical developer product that might be: the integrating engineer who wants to make their first successful call; the operator who has to deploy and monitor it; the technical evaluator deciding whether to adopt it at all; and the returning expert who just needs to look up one parameter. Each has different prior knowledge, different urgency, and a completely different definition of ‘success’. A page that serves the evaluator (‘can this do what we need?’) will frustrate the returning expert (‘just show me the parameter’).
Write down three to five distinct readers for your own product. For each, add one line: what do they already know, and what are they anxious about? Resist the urge to write ‘developers’ — that’s three or four different readers wearing one label. The more specific you are, the more the docs will write themselves.
Step two: list their tasks — as verbs
For each reader, write what they are trying to do as concrete, verb-led tasks: authenticate a request, handle a webhook retry, roll back a bad deploy, estimate the cost of a plan. Verb-shaped tasks translate directly into scannable, searchable headings, and they keep you honest. A heading like ‘Webhooks’ promises nothing and could contain anything; ‘Verify a webhook signature’ tells the reader exactly what they will be able to do by the end, and matches the words they would actually type into a search box.
- If a task shows up for several readers, mark it — it’s a candidate for your most prominent, most polished page.
- If a page you’re about to write doesn’t map to any real reader task, stop and ask whether it should exist at all.
- Rank tasks by frequency × pain. The tasks that are both common and painful earn the most care; the rare, easy ones can wait.
This analysis is your table of contents. It is also, quietly, your test plan: a doc set is ‘done’ when every high-value task has a clear home. You stop guessing whether the docs are complete and start measuring it against a list you can point to.
A team documented their product as: Projects, Members, Billing, API keys — one page per feature. Support tickets kept coming anyway. Re-mapped to tasks, the same product became: Create your first project, Invite your team, Upgrade or change your plan, Rotate an API key safely. Same features; completely different (and far more useful) documentation — because each page now finishes a job the reader actually had.
In the age of AI
Once you have the reader-and-task map, AI becomes a genuine accelerator rather than a generator of generic filler. Hand a model a specific reader and a specific task — ‘write a how-to for an integrating engineer who needs to verify a webhook signature’ — and it will produce a solid first draft you can edit. Hand it ‘write our docs’ and you’ll get plausible mush. The map is the leverage: it is the context that turns AI from a liability into a force multiplier, and it is the one input only you can provide.
Answer, then press Check. Explanations appear after.
Choose oneTasks in a doc set are best written as…
ReflectWrite three verb-led tasks for your product’s most important reader, ranked by frequency × pain.