Three ways product and feature names get mixed up in your writing
Names change, become forgotten, or never were. How do you keep your content consistent?
Does your content name organizations, products, features, and behaviors consistently? A rose by any other name might smell as sweet, but nobody would know what you were talking about.
The next time you’re auditing content or drafting something new, watch carefully for naming inconsistencies. Maybe just pick out one thing. Quick, what do you call this icon? Do you always call it that?
If your content struggles to reliably name something, then it’s unlikely that your readers can reliably identify those things—and it’ll be that much harder for them to accomplish their tasks.
The problem of inconsistent names in particular (as opposed to generalized style drift) has a few different sources. Let’s take a look at three common sources of name-related problems and how to cope with them.
Name changes: the “previously known as” problem
The first source of naming inconsistency is when a name changes: there was a definitive name, it changed, and now that content is out-of-date.
The classic example of this problem is when a product gets rebranded with a new name. The old name and the new name are well-understood. The name can be made consistent by a mechanical find-and-replace effort.
Ordinarily, this is not an intellectually challenging problem to solve, though it is tedious. The main coping strategy here is to grind it out: find the old name and replace it, in bulk if possible or line-by-line if not. The occasional backsliding while writing new text is understandable, so some vigilance after the initial change is needed too.
The anticipation of a change can add complexity, however. I worked with a client that was planning to change the name of the product for the next release, but the product team hadn’t yet committed to the final name. Technical authors relied on placeholders in new content, until the product team made a decision.
Sometimes a name change can evolve into the next kind of problem when the old guard refuses to adopt the new name.
Name uncertainty: the “also known as” problem
A second source of naming inconsistency is when there is no definitive name. If multiple names have some legitimate origin and none stands out as preferable or conventional, then inconsistency is soon to follow.
Name uncertainty is often inherited from another part of your team or project. For example, inconsistent user interface text can spillover to documentation. I’ve worked on more than one project that struggled with “domain” versus “domain name” (and other variations). Sometimes this manifests as actual style conflicts when, for example, marketing uses camelcase while the product team uses spaces.
If you can’t point to a single correct name, then assert one. Pick one name, document it in your style guide, and use it consistently. If you’re lucky, your constancy to a name can help your colleagues commit to one as well.
Namelessness: the incognito problem
A third source of naming inconsistency is when something exists in the world which has not been named and it has fallen on you to name it. Unlabeled icons and anonymous objects abound. What do you call them?
The classic unnamed widget is the aforementioned ≡, known as the hamburger button, hamburger menu, triple bar, and others. Its cousin, the ⋮, sometimes known as the vertical ellipsis, has an even broader range of nicknames. These appear in many applications, but rarely labeled. Informal names naturally proliferate.
Often, these oddities originate from outside your project or organization. Is it “standard input” or “stdin”? A “method” or a “function”? You may inherit an entire industry’s legacy of poor naming practices.
Sometimes you can find an original or authoritative option. The Start menu in Microsoft Windows hasn’t had a label in over a decade, but it’s still called the Start menu. The lack of a label doesn’t mean there’s not a name. Do your research.
If something is truly unnamed (such as your app’s hamburger button), avoid inventing your own name, if you can help it. Inventing good names is hard, so don’t do it. Look to these places for good names:
- Durable, user-facing sources that already exist (e.g., user interface writing, error messages, etc.)
- Trusted design systems, pattern libraries, and style guides (even, or perhaps especially, when these sources are maintained outside your team or company)
- Your audience (i.e., ask them, what do you call this thing?)
- Terminology that’s specific to your audience’s problem domain
The riskiest source for a new name is your own creativity. There’s a strong attraction to your insider terminology, not your audience’s problem. In its most benign form, the attraction produces noise, like UI text that says “choose one of these options” instead of “choose an appointment time”. A more troublesome version is domain pedantry, such as when a technical writer refers their audience to another “topic” instead of a “page” or “section” or “solution”. The worst is telling your inside jokes to outsiders. Trust me: the “hamburger menu” is not tasty.
As in the case of name uncertainty, pick one name from these sources, document it in your style guide, and use it.
Don’t trust your intuition
Underlying these sources of inconsistency is a risk that, when you refer to something by name, that you’ll think you know which names are right and wrong. But where do bad names come from? You and your unreliable gut.
Old names and disputed names persist when authors and editors become too comfortable with their memory of the style guide. New names emerge when authors think they know what a good name looks like, without having done the research. If this problem has a name, then it might be “overconfidence”. Or it might not; you’ll have to double check.