A Shared Glossary Kills Ambiguity Bugs

"Wait, do we mean the same thing?" is where specs start to fall apart

In a requirements meeting, words like "user," "approved," and "active" fly around. A PM uses "active" to mean "payment has completed," while an engineer implements it as "account is not frozen." Both readings are consistent with the spec document, but they point to different states. The review passes anyway, and after release a ticket shows up: "the user is active but the feature is disabled."

This isn't an implementation mistake. It happens because nobody aligned on what the word meant during requirements definition, and neither code review nor testing can catch it — the test cases themselves were written against the wrong definition.

Four fields every glossary entry needs

A shared glossary doesn't need to be exhaustive like a dictionary. Focus only on words that are prone to conflicting readings, and fill in four fields for each:

• Term: the exact wording used in specs, tickets, and conversation (include variant spellings)
• Definition: one sentence. If there are conditional branches, break them into a list
• Bad example: a real phrasing or ticket quote that previously caused confusion
• Related surface: the screen, API, or DB column where the term actually appears

A filled-in example

A real mix-up that surfaced after implementation

On one project, the word "archive" appeared in the spec more than ten times, but was never defined. The PM meant "hidden from the list, data still exists." The engineer who built it implemented a soft delete with no way to restore. The gap only surfaced when QA wrote a test case titled "restore archived data" — by then, implementation was 70% done, costing two engineer-days of rework. A single glossary line — "Archive: hidden, not deleted, restorable" — would have prevented it.

Who writes the first draft

Saying "let's build this together" usually means nobody does. It's faster to assign the first draft to whoever facilitates the requirements meeting (often the PM) and give them one hour. You don't need to start from a blank page — three sources are enough to get a usable first version:

• Nouns in recent specs and tickets that carry a qualifier ("active," "approved," "valid")
• Words from past support tickets or bug reports where someone said "oh, I meant something different"
• DB column names and status enum values — code vocabulary and spec vocabulary rarely map one-to-one

Five to ten terms is a fine starting point. The goal isn't completeness; it's building the habit of checking the glossary the moment a reading diverges.

Keeping the glossary from going stale

Three minimal rules keep it alive after the initial push:

• When a new ambiguous term comes up, one person adds it to the glossary on the spot — deferring it means nobody ever will
• Open every spec review by cross-checking that meeting's terms against the glossary (takes five minutes)
• Keep the glossary next to SPEC.md or the ticket tracker, not isolated in its own document nobody opens

Bugoon in practice

Word gaps don't stop at requirements — they show up in bug reports too. When a non-engineer writes "I can't edit this," that could mean the save button doesn't respond, or the input field is greyed out, and the wording alone rarely tells you which. Bugoon's widget captures annotated screenshots and a record of the reporter's steps, so instead of relying on how the reporter phrased it, you can see what actually happened on screen and route it straight into a GitHub Issue.

Just like a glossary, having a consistent way to close word gaps — from requirements through bug reports — steadily cuts down on rework caused by misreading each other.