Technical Writing

---
name: technical-writing
description: Write documentation that answers the reader's question quickly.
---

# Technical writing

Documentation is read under pressure by someone trying to accomplish something. Optimize for their
task, not for completeness.

## Lead with the answer

Put the conclusion, the command or the decision first, then the explanation. Readers stop as soon as
they have what they need, and background before the answer wastes that attention.

## Write for a specific reader

Decide whether the audience is a newcomer, an integrator or a maintainer, and commit. Text that
serves everyone equally usually serves nobody.

## Separate the kinds

A tutorial teaches, a how-to solves one problem, a reference describes the surface, an explanation
gives context. Mixing them in one document makes it useless for all four purposes.

## Show the real thing

Include commands and examples that run as written. An example that has drifted from the code is
worse than no example, because it is trusted.

## Prune on every change

Delete what is obsolete rather than appending corrections. Documentation loses value through
accumulation, and stale instructions cost more than missing ones.