Write Docs From the Reader's Task, Not the Feature List

A documentation approach where you ask Claude to organise around the reader's tasks — the things they're trying to accomplish — rather than cataloguing every feature and setting. The unit of docs is a job to be done, not a UI element.

Feature-first docs read like an inventory: everything is described, nothing is connected, and a reader with a goal has to reverse-engineer which five settings combine to achieve it. Task-first docs meet the reader where they are — 'how do I deploy to staging' — and walk one clear path to done. People arrive at docs with a question, and task organisation answers questions; feature organisation just describes parts.

User guides, how-to docs, onboarding, READMEs, and any documentation whose reader has a goal rather than idle curiosity.

Pure reference material — an API parameter table or a config schema — where exhaustive, lookup-oriented coverage is exactly what's wanted. Reference and task docs serve different needs; don't force one into the other.

Write docs for <feature/tool>. Organise by the tasks a reader is actually trying to do, not by listing features.
First list the top jobs a reader comes here to accomplish. For each, write a short section: the goal in one line, the steps to done, and the one thing that commonly goes wrong. Link to reference for exhaustive detail rather than inlining it.

Instead of documenting every flag of a CLI, Claude produces 'Deploy your first service', 'Roll back a bad deploy', and 'Set an environment variable' — each a short path a reader can follow — with a link to the full flag reference for the rare exhaustive lookup.

Ask Claude to infer the tasks from real signals — support tickets, common questions, the getting-started funnel — rather than from the feature list, so the docs cover what people actually struggle with, not what's easiest to describe.

• Documenting the interface instead of the job, leaving the reader to connect the dots.
• Burying the one common failure inside a wall of prose instead of calling it out.
• Mixing exhaustive reference into a how-to until neither reads well.