Glossary Building Rules

A glossary's only purpose is to make terminology consistent and unambiguous across everyone and everything that uses it — a glossary that allows multiple acceptable terms for the same concept, or that no one actually checks against, has failed at that purpose regardless of how many entries it contains.

One canonical term per concept

• Assign exactly one canonical term (and, for translation glossaries, exactly one canonical translation per target language) to each distinct concept — a glossary that lists several "acceptable" terms for the same concept with no single preferred one hasn't actually solved the consistency problem it exists to solve.
• When multiple existing terms compete for the same concept, resolve the conflict explicitly at glossary-build time (pick the clearest, most standard, or most stakeholder-preferred one) rather than leaving the decision to whoever encounters the term next in a document — an unresolved conflict just gets re-litigated inconsistently by different people.
• If genuinely distinct concepts are close enough to be confused (near-synonyms with a real difference in technical meaning), give each its own entry with the distinction stated explicitly, rather than merging them into one entry that blurs the difference.

Entry format

• Give every entry the same fixed fields: the canonical term, a concise definition specific to this domain's usage of the term (not a general dictionary definition), a usage example or context sentence showing the term in situ, and — critically — a forbidden-synonyms field listing terms that must NOT be used in its place.
• Write the definition to disambiguate this specific domain sense of the term, especially for words that have a different everyday meaning outside this domain — a glossary entry that just restates the common dictionary meaning adds nothing for exactly the terms most likely to need one.
• For translation glossaries, include the term in every target language as its own field within the same entry (not as separate glossaries per language that can drift out of sync with each other), plus any grammatical notes needed for correct use (gender, part of speech, singular/plural handling).

Forbidden synonyms

• Explicitly list near-synonyms or previously-used alternative terms that are now forbidden for this concept, not just the one correct term in isolation — without the forbidden-synonyms list, someone unfamiliar with the glossary's history will reasonably reach for one of the plausible alternatives and reintroduce inconsistency.
• When a term is renamed or superseded (a product rebrand, a corrected mistranslation, a terminology decision reversed), keep the old term listed as a forbidden synonym pointing to the new canonical entry, rather than deleting all trace of it — this catches anyone still working from outdated source material or memory.
• Review flagged/forbidden terms found in new content against the glossary as a standard step in editing or translation review — a forbidden-synonyms list that's never actually checked against incoming content provides no enforcement, only documentation.

Source-of-truth maintenance

• Maintain the glossary in exactly one authoritative location that every writer, editor, or translator references directly — a glossary that's been copy-pasted into multiple documents or tools will drift, and the drifted copies will actively cause the inconsistency the glossary was built to prevent.
• Version or timestamp changes to entries, especially renames or definition changes, so past content can be understood in light of which glossary version was in effect when it was written — this matters most for long-lived or frequently-updated domains where terminology has legitimately evolved.
• Assign clear ownership for glossary changes (who can add, edit, or deprecate a term) — an unowned glossary that anyone can silently edit tends to accumulate undiscussed, inconsistent additions that undermine the same consistency the glossary exists to enforce.

Domain scoping

• Scope the glossary explicitly to the domain, product, or subject area it covers, and state that scope — a glossary trying to cover general vocabulary alongside genuinely domain-specific terminology dilutes its usefulness and becomes harder to search for the terms that actually need it.
• Include only terms that are genuinely domain-specific, ambiguous, or prone to inconsistent translation/usage — common everyday words with no special meaning in this domain don't need an entry; adding them anyway bloats the glossary without adding value.
• When a project spans multiple domains or products, consider separate scoped glossaries with clear boundaries rather than one undifferentiated list — a shared list without domain tags makes it hard to tell which entries actually apply to the content currently being worked on.

When to add vs. when to prune

• Add a term when it appears more than once with a real risk of inconsistent usage, is ambiguous outside its domain-specific meaning, or has already caused an inconsistency in past content — a term used exactly once, with an unambiguous, uncontested translation, usually isn't worth a dedicated entry.
• Prune a term when the concept it names is no longer relevant to current content (a deprecated product feature, an obsolete process) — an actively maintained glossary is more useful and more trusted than a large, stale one where a chunk of entries no longer apply, since users start ignoring the whole thing once they hit enough dead entries.
• Before pruning, confirm the term doesn't need to be retained as a forbidden-synonym pointer for legacy content still in circulation — pruning an entry that content still references removes the disambiguation exactly where it's still needed, so prune the active-use status of a term without necessarily deleting its historical record.