# For people and agents

A documentation page has two readers: a person on the page, and a machine that retrieves a piece of it to answer a question. The documentation is written once, for both.

## Sections that stand alone

A retrieval system does not return a page. It returns a chunk, usually one section, with no context around it. So every `##` section is written to be read alone. The heading names the content specifically enough to match a search, and the first sentence works without the section before it.

## Diagrams as text

A diagram is a Mermaid code fence, never an image. The text of the diagram reaches an agent reading the page as markdown; an image reference does not. A diagram also never stands alone: the prose beneath it walks the same flow.

## One bar for every draft

The vocabulary and pattern bans apply to every author. A page written by a person and one drafted with an agent meet the same bar: no repeated frames, no filler, no decorative dashes. The patterns are listed in [Word choice](/en/documentation/style-guide/writing/word-choice/).

## Related resources

- [Components](/en/documentation/style-guide/components.md): The Mermaid mechanics and the live component set.
- [Word choice](/en/documentation/style-guide/writing/word-choice.md): The padding patterns and their replacements.