Five habits of docs people actually read

Most readers don't read docs from top to bottom. They scan for the one line they need. These habits help them find it.

1. Lead with the task

Name pages after what readers want to do: "Rotate an API key", not "Key management". Put the answer in the first paragraph, and the background after it.

2. One idea per heading

Headings are how readers scan, and how search and Ask AI find the right part of a page. If a section covers two things, split it in two.

3. Show, then explain

Start with the command or the code that works, then explain its parts. Keep examples complete enough to copy and run.

4. Use your readers' words

Write short sentences, with the words your readers use rather than your team's internal names. Explain a term the first time it appears, or link to the page that does.

5. Keep pages alive

Out-of-date docs cost more trust than missing ones. Give each page an owner, read the searches that found nothing every week, and update pages when the product changes. Every page keeps its history, so a rewrite is never a risk.