One behaviour, one term

A thing here is anything text refers to: an object, an action, a behaviour. A reader takes a new term for a new thing, so a varied term is a bug.

Happy path

1. Take the term that exists. Before you write a term, find the one already in use: the owner's term in this conversation, the project's terms (a docs guide, a glossary, a Terms section), the UI label, the identifier in the code. Use it as written. Coin a term only when none exists, define it in one sentence where the reader first meets it, and use it from then on. When the owner's term and the project's differ, use the project's and ask the owner which should change.
2. Keep it. Every later mention of that thing uses the same term, verbs included: if a step "pairs" a device, no later step "links" or "connects" one.
3. When a sentence must repeat, copy it. One behaviour described in two places (two platforms on one page, a doc and the CLI's help) gets the same sentence, word for word. A reworded sentence reads as a different behaviour.
4. Change a term only for a different thing, a different context or a stated reason. A different context is one that has its own term for the thing: the identifier in a code block, the UI label in steps. Say once that the two are the same thing ("the pairing code, pair_code in the API"), then keep each in its own context.
5. Check before sending. For each thing the text refers to, list the terms used for it. More than one, without a reason from step 4: keep one.

Gotchas

• A short form is a second term. "Question tool" for "question picker" reads as another tool. Rule: the full term every time, or define the short form once and keep the short form.
• Each product's own term. A harness's own tool keeps its own term ("AskUserQuestion"). Rule: the behaviour harnesses share still gets the shared term ("question picker") and the same sentence in each harness's section.
• The owner's term reworded. Rewording what the owner said gives their thing a second term, which they then map back. Rule: reuse their term even when you would pick another, and the same goes for a reviewer or a copy pass. Propose a change as a question to the owner, never in the text.
• A term changed in one place. The repo now has two terms for one thing. Rule: change a term in docs, UI copy, comments and specs in the same change; keep the old term only where an inbound link or an API needs it.
• One term for two things. It hides a difference. Rule: when two things behave differently, give each its own term and state the difference once.

Where the rule came from: reference/sources.md.