Writing the docs¶

These rules hold for every user page and docstring. The pages under docs/design/ record how binference was designed and are exempt.

Readers¶

Write for these readers, in this order:

Astronomy leads the examples. Every input type and every field still has its own way in.

Keep sentences to at most 25 words and instructions to at most 20.
Put one idea in each sentence.
Use the active voice.
Put a condition before its instruction: “If the chains disagree, run them longer.”

Use one word for each meaning, as defined in the glossary. A field’s own names appear only on that field’s pages, as synonyms.
Use one symbol for each meaning, as defined on the notation page.

Give each fact one home. Other pages link to it instead of repeating it.
Defaults and constants live in the Reference section, not in the theory pages.
State only measured figures, each with the setup that produced it. Every number on a page comes from code that CI runs.
Do not cite design records (“DECISIONS #n”) in user pages or docstrings. The reason for a design belongs in its issue or pull request. Older docstrings still cite them; remove the citation when you rewrite the docstring.

Add at most one “In plain words” note, with the {plain-words} directive:

```{plain-words}
Each object's estimate borrows strength from the whole sample.
```

Figures, explainers and diagrams follow the drawing rules of the design page.