Skip to content
Back to the workshop

When One Thing Wears Three Names

The words are the mental model

E
EugeneBuilding Cleo
5 min read

For a while, one object in this product had three names. In one place it was a Campaign. In another it was a Send. In a third it was simply an Email. They were the same thing. A user who built one in the composer, went looking for it in the list, and then opened it in the detail view met a different noun at each step.

I had not noticed for longer than I would like to admit. Each name had been chosen at a different time, for the screen it lived on, by a line of thinking that was reasonable in isolation. "Campaign" came from the database, where the table had always been called that. "Send" came from the action the user takes. "Email" came from the thing itself. Three sensible local choices added up to one incoherent global experience.

A vocabulary problem is a model problem

The reason this matters is not tidiness. It is that the words are the mental model. A user learns a product by building a little map of its nouns and how they relate. Email belongs to Audience. Template produces Email. When the same object answers to three names, the map will not close. The user cannot tell whether a Campaign and a Send are the same thing or two different things, so they hold both possibilities open, and that uncertainty is a quiet tax on every action they take afterwards.

I have come to treat this as a class of bug in its own right. It does not throw an error. Nothing is broken in the way a test would catch. But the surface fails to teach itself, and the failure is conceptual before it is technical. The product had not decided what the thing was, so it could not tell the user.

Renaming is the cheapest coherence you can buy

Most of the ways to make a confusing surface clearer are expensive. You can redesign the layout. You can add explanation. You can build a guided tour. Settling the vocabulary is none of those. It is choosing one noun and using it everywhere a person can read it.

I picked Email. It is the word the user already had in their head before they arrived. Then I went through every place a human reads a word on that surface, the dashboard, the list, the composer, the detail view, the page titles, and made them all say the same thing. New email. Your emails. The work was not clever. It was a sweep. But the surface went from three half-formed concepts to one, and that is a larger gain than any single feature I could have added in the same hour.

The discipline is to change the copy, never the names beneath it

There is a trap here, and it is worth naming because it is easy to fall into while feeling productive. The user-facing word and the engineering identifier are not the same thing, and they do not have to agree. The code underneath can keep calling the object a Campaign forever. The table name, the route path, the variable names, the API fields, all of those can stay exactly as they are. They are read by me, not by the user.

So the rule I hold is surgical. Change the strings a person reads. Do not touch the identifiers a program reads. The moment you decide that consistency means renaming a route to match a heading, you have signed up to break the application in order to fix a label. I inventory which is which before I start: this string is read by a human, that token is read by a machine. Only the first kind moves.

What it costs and what it returns

The cost is that the code and the copy now disagree, on purpose. A new engineer reading the code will see Campaign and the user will see Email, and someone has to know that those are the same object. I think that is a cost worth paying. The alternative, dragging the database and the routes along behind every change of mind about a word, is how you end up too frightened to fix the word at all.

The return is that the surface finally says one thing. A user who creates an email, finds it in their emails, and opens that email is no longer doing translation in their head. The product made a decision about what it is, and now it can teach that decision to the person using it.

Most of the time, when a screen feels confusing, the instinct is to add something. An explanation, a tooltip, a diagram. Often the confusing screen does not need anything added. It needs the product to decide what its words mean, and then to mean them everywhere.

E

Written by Eugene

Building Cleo, an AI marketing operating system. These posts cover the architecture decisions, technical challenges, and lessons learned along the way.

More from the workshop