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 (DDD), specifically from the book by Eric Evans. 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?
- 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.
- 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. 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.
- 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.
- 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 by Eric Evans, referenced above, you can also checkout Domain-Driven Design Distilled by Vaughn Vernon, which is exactly what its title suggests. It contains a good summary of ubiquitous languages.