What’s a Word Worth?

Terminology is a product decision, not a documentation problem

“When I use a word, it means just what I choose it to mean — neither more nor less.” — Humpty Dumpty, in Lewis Carroll’s Through the Looking-Glass

---

The support ticket read: “How do I activate my subscription?”A short, to-the-point question. The answer should be easy.

But the answer depends on who you ask. Marketing says activate means completing the purchase. Product says it means provisioning the account. And Development says it means flipping a feature flag. Three teams, one word, three different things happening in the product. The documentation uses all three definitions, sometimes in the same topic.

Nobody noticed until a customer couldn’t figure out why they’d paid but couldn’t log in.

This is not a communication problem that starts long before anyone opens a document editor. You’ve got a common word problem.

The terminology gap

Every product develops a working vocabulary. The trouble is that it develops separately inside each team. Marketing invents terms that sound good in campaigns. Product uses whatever the designer named a component in Figma. Development names things after the underlying system behavior. None of these groups talks to each other about words until a customer is confused or a support queue grows. If you’re lucky, you notice this confusion while writing documentation before a customer sees it.

Documentation sits in the middle of all three. A technical writer pulling information from a sprint ticket, a product brief, and a Slack conversation will find three different words for the same thing. If they pick one without establishing it as the standard, they’ve made a local decision that doesn’t stick. The next person who touches that doc or writes a new one starts the variation over again.

The downstream effects are predictable. Support gets tickets asking why Step 3 of the setup guide doesn’t match what’s on the screen, because the guide says workspace and the UI says environment. Sales gets questions about features that exist but aren’t recognized under the name the prospect heard in a demo. Onboarding stalls because new users are mapping one set of terms they learned in a webinar onto a product that uses a different set.

The fix isn’t a style guide. Style guides govern grammar and formatting. (You have a style guide, right? RIGHT??) What’s needed first is a wordlist: a short, shared agreement document or spreadsheet on what things are called and what those names mean.

Building the list before writing the docs

A wordlist is not a glossary. A glossary defines terms for readers. A wordlist aligns the people doing the writing and the reviewing before a word appears in any customer-facing content.

The process is straightforward. Bring one person from marketing, one from product, one from development, and the technical writer into a working session. Pick the ten to twenty terms most central to the product. These are the words and phrases that appear constantly, the ones that have caused confusion in support or sales, the ones where you’ve noticed different teams using different words. Write down what each team calls each thing. Where there’s disagreement, decide. Document the decision.

Disagreements about terminology are almost always disagreements about how the product works, or how it should be described to different audiences. Marketing may call something seamless integration because that’s what resonates in a pitch. Engineering calls it event-driven sync because that’s what it is. Neither is wrong in context, but documentation has to serve the user doing the task, not the marketer closing the deal or the engineer who built it. The wordlist forces that negotiation to happen explicitly, once, in a room, rather than implicitly, repeatedly, across every piece of content that ships.

The output is a one-page reference: preferred term, definition in plain language, terms to avoid, and a note on context if the term behaves differently in different parts of the product. That’s it. The list doesn’t need to be exhaustive to be useful. It needs to be authoritative.

Once you have it, it becomes the first thing any new writer, contractor, or AI-assisted workflow checks before producing content. It also becomes the reference point for review: when a subject matter expert substitutes their preferred term in a draft, the wordlist is why you push back.

What the style guides say

Both Microsoft and Google have done serious work on this. The Microsoft Writing Style Guide is explicit: use words with a single, clear meaning. Avoid jargon. When a technical term is necessary, define it once, use it consistently, and don’t introduce synonyms. The guide treats synonym variation as a bug, not stylistic variety. It also addresses the instinct toward variety that many writers have — the feeling that using the same word repeatedly is somehow lazy. In technical documentation, that instinct is wrong. Repetition is clarity.

The Google developer documentation style guide takes a similar position. It recommends plain language, warns against using multiple terms for the same concept, and pushes writers to define terms in context the first time they appear. Google’s guide also addresses the reverse problem: don’t use the same word for different things. If instance means a virtual machine in one section and a running process in another, the reader has to carry that ambiguity through every task they try to complete. Most won’t. They’ll guess, get it wrong, and file a ticket.

Both guides point at the same problem Humpty Dumpty named: when everyone decides words mean what they choose them to mean, readers lose. If you use a word three ways, it has three meanings. Readers will pick whichever one fits their existing mental model, which may not be the one you intended.

These two style guides also include term and word lists you can incorporate or reference in your project’s list. There’s no need for you to redefine!

What this requires

Terminology alignment is less of a documentation task and more of a product decision. Technical writers can propose the wordlist and run the process, but the decisions have to be made by people with authority over how the product is described, and those decisions have to hold across teams.

That’s the part most organizations skip. They’ll accept that documentation should be clear, then undermine it by letting marketing rename a feature for a campaign without telling anyone, or letting engineering ship an error message that uses a term the wordlist retired six months ago. A product changelog goes out using a new name for an existing concept. A sales deck introduces a term no one else is using yet. Each of these is a small fracture. Enough of them, and the wordlist is no longer authoritative. It’s become a quaint artifact.

The wordlist needs an owner, and that owner needs a standing agreement with the teams that ship customer-facing content. New terms go through a lightweight review before they appear anywhere. Existing terms don’t get swapped out without a decision. The bar isn’t high. It can be a short conversation and an update to a one-page document. But someone has to be responsible for making that happen and following up.

As technical writers, we’re well-positioned to own this. Daily, we see every place where language breaks down. We’re downstream of every team that generates terminology. We know where the inconsistencies are because we’re the ones dealing with them and deciding what to do about them in the moment. Formalizing that role — turning a reactive cleanup task into a proactive governance function — is one of the clearest ways you can drive product quality rather than just suggest it.

When a customer reads your documentation, they’re building a model of how your product works. Every inconsistent term introduces friction. Every synonym creates a branch in that model that they have to resolve on their own. Most of them won’t. They’ll open a support ticket, or they’ll leave.

The documentation isn’t the problem. The words are. In your product, unlike Wonderland, words can’t mean whatever anyone chooses. Work together. Start the list. Enforce it.

---

Steve Arrants is the principal of Green Mountain Docs, specializing in documentation strategy, docs-as-code workflows, and AI-augmented documentation systems.