# Writing documentation an agent can actually use

Documentation written for humans assumes a reader who can skim, infer, and click
around. An agent reads linearly, with a token budget, and acts on what it finds.
A few habits make a document far more useful to that reader.

## Put the answer first

Lead with the fact, the command, or the schema. An agent that finds what it needs
in the first 200 tokens never has to load the rest. Save the narrative for after.

## Be explicit, not clever

Spell out the thing. "Set `REACH_BASE_URL` to your instance URL" beats "configure
the endpoint as appropriate." Agents don't reward implication; they reward
copy-pasteable specifics.

## One document, one job

A page that does one thing — one API, one procedure, one concept — is easier to
link to and cheaper to load. Split compound topics into linked documents instead
of one sprawling page.

## Make the structure machine-legible

Real headings, real code fences with language tags, real tables. An agent parses
your `##` and your ```` ```bash ```` the same way a human's eye does — but only if
they're actually there.

## Keep it addressable and versioned

When a fact changes, publish a new version rather than editing in place silently.
An agent that cited "v3" can still fetch exactly what it read. On reach, every
edit is a new immutable version with a recorded change note — so the history is
the documentation of how the documentation changed.