---
title: "Naming Content Types Using a Ubiquitous Language"
url: "/articles/naming-content-types-using-ubiquitous-language"
type: article
date: 2020-04-08
updated: 2020-04-08
---

# Naming Content Types Using a Ubiquitous Language

#  Naming Content Types Using a Ubiquitous Language 

 The development of a ubiquitous language for things like content types is an ongoing conversation, but the terms used should be driven by stakeholders and domain experts, and not developers.

 By

 [  Matt Robison   ](/about/matt-robison) 

 April 8, 2020

  

The team of editors who populate content on Newspaper, Inc. has asked the development team to add another image field on the articles they write, one that caters to Pinterest sharing. The project manager writes up the ticket, and the development team gets to work. They add the field to the *Article* content type. They demo it later that week, and everyone seems happy.

Then some complaints start coming in. A few of the editors can't find the field on the articles they are writing. The development team checks to make sure the field is still there and that everyone has the right permissions, but everything checks out. They ask for a demo of the problem.

One editor attempts to create content of the type, *News Item*. The field, of course, is not there. "That's not an article," the development team explains.

"What? Of course, this is an article!" says the editor, a little frustrated. The development team can't detect the lack of an uppercase letter in the word "article." So, they go on to pedantically explain what Drupal content types are, what a real *Article* is in terms of development, and all the while, the editor just gets more and more frustrated. This organization could benefit from a shared, ubiquitous language.

## What is a ubiquitous language?

The term "ubiquitous language" comes from the world of [Domain-Driven Design](https://en.wikipedia.org/wiki/Domain-driven_design) (DDD), specifically from [the book by Eric Evans](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215/ref=as_li_ss_tl?crid=1SQ7D0UJMMC63&keywords=domain+driven+design&qid=1582153592&sprefix=domain+driv,aps,159&sr=8-2&linkCode=sl1&tag=newlibecrea-20&linkId=1f4d11db798b68447112491248d84940&language=en_US). Still, you don't have to fully commit to DDD to benefit from some of its recommendations.

A ubiquitous language is a vocabulary shared by everyone involved in a project, from domain experts to stakeholders, to project managers, to developers. This language should be used in all documentation, tickets, conversations, meeting invites, post-it notes on your computer, chalkboards that only appear in your dreams — everywhere. The goal is to reduce the ambiguity of communication.

Ideally, each term that surfaces corresponds to something concrete in the code. When people talk about an event, there is a content type named *Event* in your Drupal installation, for example.

But don't stop at just content types. The name of a View should also reflect how people actually talk about it. Or a block. If your marketing team consistently calls the email capture block a "lead generation form," think twice before naming it "newsletter sign up" in your code. Your module names should also reflect the vocabulary used by the organization and not just the whims of the development team.

## Driven by stakeholders or domain experts

The development of a ubiquitous language is an ongoing conversation, but the terms used should be driven by stakeholders and domain experts, and not developers. If your editors think of everything they post on the website as an *Article*, then there should probably just be a single content type named *Article*. Taxonomy fields can handle permutations to handle the different contexts, the terms themselves controlled by a subset of the ubiquitous language, such a *News Item*, *Press Release*, or *Announcement*. (Or, leverage some of the techniques listed below to unify the concept in code). But this depends on the organization.

In some places, editors and teams might be used to referring to different types of content by different names, even though they might be similar. In that case, it might make sense to have different content types for *News Item and announcement*. It might not make the most sense from a technical perspective, but if it eases communication and reduces ambiguity, it makes sense.

When you have a true ubiquitous language, stakeholders and end-users can talk about things *in the code* with developers, and with some confidence. Conversations can delve deeper. Problems, needs, and solutions will surface with greater clarity.

## Benefits of having a ubiquitous language

First, clearer communication. **Less ambiguity**. It makes it less likely to have misunderstanding and mismatched expectations.

Second, **a useful shorthand can develop**. Once the ubiquitous language becomes more ingrained, and good habits are established, an enormous amount of information and context is communicated when someone uses the word "article."

Third, people involved become more aware of potential issues when they come up, **creating a beneficial feedback loop**. Developers can push back against terms that are ambiguous or inconsistent. Stakeholders have an extra leg to stand on to insist that developers use terms that they can understand or ask questions about words that seem too awkward to use in everyday conversation. This leads to more back and forth communication that strengthens the shared language and makes it more relevant for everyone.

Naming things is one of the hardest problems in programming. It lets developers offload some of that cognitive effort.

If your editors are continually using the word *Lede* to refer to the initial summary of an article that appears in lists of articles, it surfaces an opportunity to have a specific field for this concept. In turn, this leads to greater clarity in code and is an opportunity to make the whole system better and more robust.

## We didn't name things right. Or the names evolved. What now?

Things are rarely right the first time, and in today's development world, iteration is king. So what can you do if the code doesn't reflect the language you are using, and you're afraid the concrete has been drying for too long?

1. Change the label. While machine names in Drupal can be harder to change, labels are easy. This isn't ideal, because machine names can be used throughout custom code, but at least there will be something concrete on the website, and in the code, that conforms to the ubiquitous language.
2. Use Decorator functions and classes. If you have several content types that should map to a single concept in your ubiquitous language, like in the example that opened up the Article, [consider using a wrapper class](https://www.lullabot.com/articles/maintainable-code-drupal-wrapped-entities). A wrapper class called *Article* can encapsulate various content types and add additional functions for specific business logic. It is this wrapper class that is used throughout your code and what maps to the vocabulary used in the ubiquitous language.
3. A mapping document in your documentation that everyone understands. This helps translate concepts from the ubiquitous language to the code. In practice, this could become just another document that seldom gets updated (the threat hanging over *all* documentation), and so should be used as a last resort. But it could be helpful in certain situations. Always try to map directly to the code, if possible.
4. Migration. In some cases, migrating several content types into a single type, so your Drupal installation better matches the ubiquitous language might be worth the time and effort. If you are preparing to make a big development push and need better foundations, or you're migrating from another CMS or to a newer Drupal version, the opportunity might present itself.

## Conclusion

A ubiquitous language used everywhere throughout your organization, with discipline and intention, has the power to help make your communication easier and your code more maintainable. By mapping the shared language directly to concepts in the code, and in this specific case, Drupal content types, requirements can be made more explicit, and discussions between stakeholders and developers can be more profitable.

Beyond [Domain-Driven Design](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215/ref=as_li_ss_tl?crid=1SQ7D0UJMMC63&keywords=domain+driven+design&qid=1582153592&sprefix=domain+driv,aps,159&sr=8-2&linkCode=sl1&tag=newlibecrea-20&linkId=1f4d11db798b68447112491248d84940&language=en_US) by Eric Evans, referenced above, you can also checkout [Domain-Driven Design Distilled](https://www.amazon.com/Domain-Driven-Design-Distilled-Vaughn-Vernon-ebook/dp/B01JJSGE5S) by Vaughn Vernon, which is exactly what its title suggests. It contains a good summary of ubiquitous languages.

 Published in:

- [  Drupal Development   ](/topics/drupal-development)
- [  Drupal Site Building   ](/topics/drupal-site-building)

 

   You must have JavaScript enabled to use this form.

## Get in touch with us

### Tell us about your project. We'd love to hear from you!

 First Name  

 Last Name  

 Your email address  

 Your organization  

 How you heard about us  

 Tell us more 

     Leave this field blank