Maintain a Product Glossary Without Freezing Useful Language
Maintain a product glossary with meanings, examples and scoped exceptions so consistent terminology does not make the writing less accurate.
TL;DR
- Decide meaning before policing words: define the underlying concept so writers can use consistent language without forbidding useful synonyms; start by addressing terms that actually cause confusion in context.
- Use operational entries: record a preferred term plus meaning, example, known confusion and owner, and show a correct-use sentence so writers can apply the glossary in real drafts.
- Keep glossaries small, review changes and exceptions: favor a maintained set of consequential terms, treat renames as content updates, and retire or fix entries that keep causing questions.
Define the concept before the preferred word
A content glossary is useful when it helps writers describe the same thing consistently. It becomes restrictive when it treats every synonym as wrong without explaining the underlying concept or the context in which the preferred term applies.
Start with terms that cause actual confusion. In a fictional publishing product, workspace might mean the account container, project might mean one website and article might mean a content item. Those distinctions affect instructions. A glossary that merely lists the words without their meanings does not help a new writer use them correctly.
Keep the first version small. A maintained set of consequential terms is more valuable than a large imported dictionary whose definitions nobody owns.
Give each entry an operational shape
Record the preferred term, meaning, example, known confusion and owner. Add a source or product reference when the definition depends on a specific implementation.
| Term | Meaning in the fictional product | Common confusion |
|---|---|---|
| Workspace | Shared account container | Not the same as one website |
| Project | One configured publishing context | Not every article assignment |
| Draft | Saved content not yet released | Not necessarily unreviewed |
| Published | Delivered to the public destination | Not merely scheduled |
The table illustrates how definitions can prevent workflow mistakes. It is not a statement of every product's terminology. Your glossary should reflect the actual system your audience uses.
Include a sentence showing correct use. “Choose the project that owns this website” is easier to apply than an abstract definition alone. Where a term has several valid senses, name the intended scope rather than forcing one universal meaning.
Related reading: A Content Approval Workflow From Brief to Published Revision.
Preserve exact labels when they help the reader
An interface label may need to appear exactly as the user sees it, even if it differs from ordinary house style. A historical quotation may also preserve older terminology. Record these as scoped exceptions rather than silently changing the glossary's general rule.
For example, a product setting labeled Team may remain Team in an instruction while the surrounding article uses workspace for the broader concept. Explain the relationship so the writer does not “correct” the interface label into something the reader cannot find.
Our content brief template can point writers to the relevant glossary entries. Do not paste the entire glossary into every brief; select the terms that materially affect that assignment.
Review proposed additions through real examples
When someone requests a new rule, ask for a sentence where the current terminology causes a problem. This keeps the glossary connected to reader needs rather than personal preference.
Decide whether the issue is a definition, a preferred expression or a one-off editorial choice. Not every disagreement requires a permanent rule. A glossary can become difficult to use when it tries to encode every stylistic decision made in one article.
Assign a person who can confirm the meaning, especially for product capabilities. A copyeditor can maintain presentation conventions, but a product owner may need to decide whether two terms describe the same behavior.
Handle a term change as a content update
When a product term changes, record the old term, new term, effective context and reason. Then identify affected drafts and published pages. Do not assume every historical occurrence should be replaced.
Review examples in context. A current instruction may need the new label, while an article describing a past release may need the historical name. The goal is accurate understanding, not a zero count of the old string.
Keep a short change history so the next editor can understand why an exception exists. Without that context, they may reintroduce an old ambiguity or remove a deliberate distinction.
Keep the glossary usable
Review entries that repeatedly generate questions or exceptions. They may need clearer examples, narrower scope or retirement. A rule that writers routinely misunderstand is a documentation problem worth fixing.
Choose a review cadence appropriate to product change, and allow urgent factual updates when a label or concept changes. Stable definitions do not need to be rewritten merely to show activity.
A useful glossary makes precise writing easier. It gives writers enough shared meaning to be consistent while leaving room for accurate quotations, interface labels and audience-appropriate explanations.