
Documentation fails in two ways that look unrelated and are both structural. The first is a page full of background nobody asked for. The second is a page written for the wrong reader — internal shorthand in a customer doc, or marketing tone in a reference page.
Two skills address the failures in the right order: Doc Outline for structure, Tone Shift for register.
The short answer
Outline before writing, and shift tone as a separate pass. Doing both at once produces a draft that reads well and answers the wrong question.
The outline test
Doc Outline starts from the three questions the reader arrives with. Each section must have one of those questions behind it; sections that exist because the writer wanted to explain something are removed.
That test is why backgrounds disappear. A background section answers 'why does this exist', which is rarely the reader's first question. If it is, it becomes a section with a question; if it is not, it becomes a link.
The tone pass
Tone Shift rewrites a draft for a stated audience and register while keeping claims, numbers, and structure identical. The check is a diff of the claims: if a caveat disappears in the rewrite, the pass failed.
That check is what makes tone shifting safe. Without it, 'make it simpler' is permission to remove the limitation that made the doc honest.
The two passes compared
| Pass | Fixes | Check |
|---|---|---|
| Outline | Wrong sections | Every section has a reader question |
| Tone | Wrong reader | Claims and caveats unchanged |
| Neither | — | Reader asks support instead |
The third row is the cost of skipping both, and it is easy to measure: the tickets that quote a documentation page.
A worked example
A feature doc arrives with a long intro, three screenshots, and one line about the limitation. The outline pass turns it into: what this does, how to use it, what it will not do. The tone pass produces a customer version and an internal version from the same draft, with the limitation intact in both.
Where skills stop
Neither pass reads the code. A doc that describes behaviour accurately is still describing yesterday's behaviour if the feature changed, and no writing skill catches that. The version check is separate and mechanical.
Frequently asked questions
Can I skip the outline for short pages? Often yes. A one-screen page rarely has structure problems.
Does tone shifting work for support macros? Yes, with the claims diff as the check. See support macro.
What about docs as a retrieval corpus? Structure and retrieval align: task-shaped titles help both. See docs as retrieval corpus.


