The best compliment a manual can receive is that nobody mentions it. It simply worked, and the reader got on with their day.

Start from the task, not the system

Engineers document systems. Readers arrive with tasks. Those are different shapes, and the gap between them is where most documentation fails.

A section titled Configuring the authentication middleware serves the author. Letting your users sign in with Google serves the reader. Same content, entirely different discoverability.

Assume interruption

Nobody reads documentation start to finish. They land mid-page from a search result, skim for the shape of an answer, and leave. That means:

• Headings that describe outcomes, not components
• Code blocks that run as written, with no elided setup
• Every acronym expanded once per page, not once per document

Show the failure case

# what most docs show
pnpm install && pnpm build

What readers actually need is the line above the one that breaks — the version mismatch, the missing environment variable, the permission that has to exist first. Documentation that only covers the happy path sends people to a support queue.

Edit for what you can remove

The second draft of a manual should be shorter than the first. If it is not, the editing pass was really a writing pass.