The glossary must cover UI, docs, and search

What it is

If the preferred term is written into the nav while the help centre, release notes, search synonyms, and support scripts each keep their own, the glossary is a table that never joined the system. The glossary must cover UI, docs, and search: the same concept points at the same node on the button, in the explanation, and in the index. Drop any channel, and people relearn at every hand-off, or they search the product for a name that exists only in the docs.

Coverage is not three copies. It is one table consumed by three channels: the UI takes the preferred term, docs take the preferred term plus a statutory name when required, search takes the preferred term plus aliases.

Why it happens

People carry words across channels. After reading “workspace” in help, they look for “workspace” in the product; after learning “project” in the product, they type “project” into search. If each channel keeps a table, the transfer fails, which looks like a missing feature and is actually a word that did not follow the person. If support and bots read a fourth table, conversation logs cannot be linked back to UI objects, and the issue is filed as a new request.

Search is the channel most often left behind: designers own the UI table, content owns help, search engineering owns synonyms. The three updates drift, and the newest rename lives in only one channel.

Studying it

Track words across channels; do not review whether a single glossary file looks tidy.

• Paradigms: pick core concepts, harvest wording from UI strings, help and release notes, and search-synonym config, and build an alignment matrix; on tasks, start from a documentation sentence and find the matching control, or search with a word learned in the UI.
• Independent variables: whether the table is a single source, whether a rename is pushed to all three channels together, whether docs may keep an old statutory name.
• Dependent variables: count of cross-channel splits, success locating the UI from docs, recall when searching with the UI word.
• Methodological note: sampling the homepage and flagship help articles overestimates coverage. Sample corner pages, mail templates, and error-code copy after a rename. Automated string diff finds literal splits; co-reference still needs a person.

Where it stops holding

External legal text must keep statutory wording; the docs channel may show the official name, but it has to link back to the UI preferred term rather than letting the legal text rewrite the button. Error messages from third-party integrations are outside this glossary; wrap and translate them into the preferred term rather than demanding the vendor change. Community-contributed docs lag; coverage needs a split—“community copies may keep the old word, official channels must use the new one”—rather than pretending the globe switches at once.

Applying it

• Make the glossary a shared source for three channels. Changing a preferred term ships a change in nav, help, and search config together.
• The release checklist includes UI copy, help retrieval, synonyms, mail, and error text—four draws of the same concept.
• If docs must show an old or statutory name, join it once, then return to the preferred term.
• Verify by pulling a word from a concept’s help paragraph, finding the control in the product, and querying search. If the three do not meet on the same object, that channel is missing; it is not a “tone” issue.

Related

• Within the group: G1.08.1 Inconsistent terms are read as different features · G1.08.2 Synonyms need mapping, not coexistence
• Adjacent: G1.10 Controlled vocabularies and synonyms · T1.04 Terminology consistency and glossaries · T3.02 Organizing and retrieving help
• Search terms: glossary coverage · terminology management · search synonyms