A product glossary before Friday’s dashboard release

One dashboard, three names for the same thing

Imagine a developer team preparing a dashboard release for Friday. The interface says “workspace,” the setup instructions say “project,” and a support reply calls the same thing an “account.” Each writer understands what they mean. A new user has to guess whether these are three different things.

A product glossary fixes this kind of confusion. It is a shared list of important product terms, their meanings, and the names your team agrees to use. You do not need a specialist tool or a large documentation team. A small table in a shared document can be enough.

A glossary records meanings, not just preferred spelling

A spelling list might tell you to write “API key” rather than “API Key.” A glossary goes further: it says what an API key is, where the term belongs, and which alternatives could confuse readers.

This matters because terminology is part of the product experience. Users carry words from the interface into documentation, search queries, and support conversations. When those words change unexpectedly, they have to stop and reinterpret the product.

A glossary is also different from a style guide. A style guide covers broader writing choices, such as capitalization and tone. A glossary connects particular words to particular concepts.

Your first ten terms should come from real friction

Start with a short audit, not a dictionary-writing project. Read your main onboarding page, inspect the dashboard navigation, and review a few recent support conversations. Look for places where two names describe one thing, or one name describes two things.

• Collect labels users must understand to complete their first task.
• Include billing words that affect purchasing decisions.
• Flag technical terms that have a product-specific meaning.
• Prioritize names that already cause questions or inconsistent search results.

Ten useful entries are better than a hundred speculative ones. For a developer product, that initial set might include API key, request, model, balance, and usage. Only include terms your product actually uses.

Each glossary entry needs a definition and a boundary

Use the same small template for every entry: preferred term, definition, usage example, alternatives to avoid, and scope. Scope tells writers whether the term belongs in the interface, documentation, API reference, or all three.

For a fictional dashboard, an entry might read: “Workspace: a shared area containing a team’s projects and settings. Example: Create a workspace before inviting teammates. Avoid: account, when referring to this shared area. Scope: interface and help documentation.”

Notice the boundary: a workspace is not an account. That distinction is often more useful than a polished definition. Where necessary, add a related term so readers can understand the difference.

Do not rename fixed API fields just to match a preferred label. If an existing field uses a different word, document the relationship explicitly. Consistency should make integrations easier, not break them.

One reviewer should settle disputed names

Ask someone from engineering, support, and product to review the first draft. Each sees different problems: implementation mismatches, customer misunderstandings, and interface constraints.

Give one person responsibility for recording the final decision. Otherwise, the glossary can become another place where competing names accumulate. Choose terms based on user understanding and existing usage, not simply on who argues most strongly.

For each change, record a brief reason. “Matches the dashboard label” is enough. That note helps the next teammate avoid reopening a settled discussion without new evidence.

AI drafts need the glossary beside the assignment

If you use AI to draft release notes or documentation, include the relevant glossary entries with the task. Ask the model to preserve preferred terms and flag ambiguity rather than invent replacements.

For teams using AI across developer tools, RelayVano is a practical pay-as-you-go relay that works with OpenAI-compatible SDKs. Sign up for RelayVano if that fits your workflow, and keep your glossary alongside your drafting instructions.

Friday’s release review should include a terminology check

Before publishing, search the changed screens and documents for discouraged alternatives. Check that examples use the agreed names, then add any newly introduced concept to the glossary.

Keep this review small and repeatable. The goal is not identical wording everywhere. It is making sure that when users encounter the same concept again, they recognize it immediately.