Ubiquitous Language: the Good, the Bad, and the Lessons

Ubiquitous Language Is Great

Ubiquitous Language is the idea of defining a common language to be used at all levels in your product: user interface, documentation, client presentations, code, etc. This language should be shared between domain experts, users, marketing, and devs.

The history of languages shows that Linguistic prescription (defining and enforcing a standard language) is tricky. For example, every time the Académie Française has tried to impose freshly minted terms to replace Anglicisms – such as email, upload etc. – it failed. Most French people kept using the English words. If only because of reluctance to change, a fully ubiquitous natural language is not realistic.

So you may wonder: is Ubiquitous Language worth the trouble? How helpful is it?

Avoid Duplicated Effort

If you are familiar with Microsoft Word, you may have noticed you have two ways to color the background of your text: “Text Highlight Color” and “Shading”.

There is a significant overlap between both features, but they do not cover the same cases and they do not work well together. They are – most likely – two separate implementations covering a single need. A user might have a hard time deciding whether their text should rather jump off the page or just pop…

Looking at these buttons, I cannot help but think the lack of a common language resulted in waste: having to implement and maintain a feature twice.

Avoid Bugs

It is possible to open hidden presentations (without a window) in PowerPoint. When all presentation windows are closed, PowerPoint will remain active as long as a hidden presentation is opened.

In one of our sprints, we needed to implement a routine to force close all such presentations. But in our code base, we had an older method named GetHiddenPresentations that listed minimized presentations.

As you can guess, we ended up force-closing all minimized presentations. This – definitely – was not a welcomed feature! In the post-mortem that followed this bug, we decided to use “windowless” and “minimized” instead of the ambiguous “hidden”. We felt this simple wording change would have avoided the mistake from the beginning, and would have helped us spot that bug during the review.

Ubiquitous Language Is Hard

Ubiquitous Language sounds simple, but – since it is all about naming things – it is not. I’ve been struggling with it ever since I joined UpSlide. Please don’t tell my colleagues 😉

In 2022, we wanted to simplify the way our users apply style to their PowerPoint tables. We already had a “Table Styles” feature, so we came up with an idea: a menu that would pop up when users select tables.

It was the first time we implemented such a menu, so we had a question…

👉 What should we name this kind of menu?

Let’s Brainstorm!

Imagine you’re part of our team. You are looking for the name of “a context-dependent menu that pops up to nudge users”).

Gather a few colleagues and start throwing ideas around.

Once someone suggests “minibar 🍸”, you can all agree you have run out of ideas.

There Can Only Be One!

Now it’s time to eliminate ideas…

• Let’s start with the obvious ones, “Menu” and “Suggestion” are too generic. Out!
• “Popup” is not so bad, but the word has gained such a bad reputation (because of website ads) that it’s out the window. “Pop menu” removes some of that discomfort but sounds unfamiliar.
• “Prompt¹” means something else to devs (Command Prompt or Javascript prompt).
• From a marketing perspective, “Toolbar” / “mini toolbar²” do not spark joy. Pre-Office 2007, toolbars were the rage³, but they disappeared when the ribbon arrived.
• “Context Menu” sounds OK, but it is the name commonly used for the right-click menu…

Let’s assume that you’ve settled on “Contextual menu” (like we did at the time). You can now proceed to use that term everywhere: code, documentation, discussions, etc.
And – because you want this Ubiquitous Language approach to work– you’ll make a point of correcting anyone who uses something else: “Careful, this is not a popup⁴, it’s a contextual menu.”.

#happily-ever-after

Marketing Called: They Have a Better Name…

While the feature is getting ready for the general release, our fellows from Marketing have gathered insights from users and concluded that the feature should be named a “prompt”.

To keep a Ubiquitous Language, we now have to rename all occurrences in:

• Code: IDEs are great nowadays and make this step easy. (<3 JetBrains)
• Documentation: this one is more painful, because:
  • our documentation is spread across several tools⁵ (Notion, a bit of Zendesk for end-users, and an Azure DevOps wiki for technical topics);
  • search and replace is a blunt tool.
• my head: on this front, tooling cannot help… Once they have gotten used to it, people will have a hard time avoiding the now-obsolete name. So “Contextual Menu” will keep popping by in emails, and other conversations. It eventually gets better, but the transition is painful.

More Surprises 😅

Remember when I said renaming the code was easy? Well, I lied… Some occurrences of “Contextual Menu” are serialized in our user settings.

When this happens, you must choose between a breaking change and quasi-ubiquitous language.

The same kind of issue can also happen with old emails or messages: they cannot be fixed and might cause head-scratching later on.

By the time we got around calling those menus “Prompt”, ChatGPT arrived. And with it, a new meaning for “prompts” emerged. For anyone in the software industry, a “prompt” is now the input given to a Large Language Model.

So, should we rename our “prompts” to avoid confusion, or should we keep that name?

Lessons

“Well-established” Trumps “Cool”.

We are a Microsoft 365 add-in, deeply integrated within Microsoft Office. We were implementing a feature that behaves like the Office “Mini toolbar”… From a Ubiquitous Language perspective, this makes a very strong case for naming our feature “Mini toolbar”.

Name Deliberately

When we started working on the Proof of Concept for Table Styles, we delayed thinking about the feature name. It made sense because we were unsure of what we could build exactly. By not picking a name, we encountered many challenges along the way.

In retrospect, we should probably have…

• Deliberately picked a dummy name for the future feature. Maybe even a silly one – say Stylinator – to make changing it easier.
• Started looking for a good name as soon as the final feature behavior was clear.
• Involved all parties (devs, product, marketing, domain experts) in that search.

Conclusion

Despite all your efforts, external factors will force you into renaming things. In 2022 it might have been OpenAI that changed the meaning of “prompt”. In 2023 it might have been Microsoft's decision to rename Azure AD to Entra ID. Change is inevitable.

Over the years, I have found it helpful to view Ubiquitous Language as a journey, rather than a destination. Maintaining a common vocabulary can be a pain at times, but it is often worth it. Trust me, you do not want the blood of those minimized presentations on your hands 😅

What about you? What is the worst bug you have ever met that was caused by a misunderstanding?

Notes

1. This was early 2022, before ChatGPT, so “prompt” was not commonly associated with AI.

2. Microsoft Office has a feature named “mini toolbar” that behaves like our menu.
   

3. In the 2000s, it was common for software to bundle browser toolbars, and you could end up with an unusable browser…
   

4. When developing the Proof-of-Concept, the initial name we used was “popup”.

5. We are actively looking at reducing the number of tools we use for our documentation.

Cover photo source.