Controlled Vocabulary - Kristin McKee - Write the Docs Portland 2018 Lightning Talk

A controlled vocabulary is a living, organized list of terms, phrases, and concepts designed to help people navigate a specific context—and the payoff is practical: fewer misunderstandings, more consistent documentation, and clearer alignment between product teams and readers. Kristen McKee, working at Jama Software, frames the idea around a year-long effort to untangle how the company’s documentation used words that looked familiar but carried different meanings for different people.

When she arrived, Jama already had about 600 pages of documentation assembled over a decade. To understand what existed, she approached the docs like an “explorer and archaeologist,” tracking recurring terms and noticing patterns. One example was the word “visual view.” It appeared frequently, but it didn’t mean the same thing to her as it did to others—an early signal that the documentation relied on an “implicit vocabulary,” where teams assume everyone shares the same definitions.

That gap became concrete during a standup meeting. Someone repeatedly referenced “sprinkles,” and only after the group listened closely did it click that the person was actually talking about “Sprint goals.” The moment illustrated how easily shared assumptions about everyday words can break down inside a specialized workplace. People hear what they expect to hear, not necessarily what’s being said.

To bring meaning out of the shadows, McKee spent the year reviewing documentation in depth, interviewing customer-facing staff, and visiting departments including marketing, product support, and engineering. The goal wasn’t just to list terms—it was to ask which words customers and teams wanted to understand, and which words others wished everyone else knew better. The research reinforced a key finding: even when people use the same word, they often attach slightly different meanings.

From there, she offers concrete guidance for building a controlled vocabulary. The foundation is strict mapping: one meaning for one term, and one term for one meaning. She also recommends pairing certain verbs with nouns consistently—for example, deciding whether the system uses “add an item” versus “create an item,” rather than letting both drift. Finally, she emphasizes that controlled vocabularies should be treated as living references that grow over time, not as static rules for “right” and “wrong.”

The benefits are both reader-facing and internal. Consistency helps users learn a term once and reuse it, while documentation can become shorter and more succinct because definitions don’t need to be repeated. Confusion drops for internal teams too, and—perhaps most strategically—shared understanding can help guide product vision by making communication more precise across functions.