Chapter 9. Learning Domain Language
To build usable business software, you must first understand the domain. In this chapter, we will show how Domain Storytelling can help you to build up domain knowledge. Learning the language of the domain experts is the most important task because it is the key for effective conversations about business processes and software requirements.
This chapter is for you in the following cases:
• You are new to a domain (e.g., because you are a contractor) and need to “crunch” domain knowledge.
• You want to bring together domain experts from different departments to cross department boundaries and challenge assumptions.
• The software that you are working on does not use real terms from the domain, and you want to change that.
• You work in an organization where no real domain language exists, and you want one to emerge.
Stefan’s Roadwork Story
A few years ago, two colleagues and I met with a public authority that plans roadwork for a large city. They had a simple question: How can software help us to better coordinate our construction sites?
To answer this question, we had to learn about a domain that we had no prior experience with. We needed to understand how the domain experts work, what they work with, and what problems they struggle with. We needed to be able to talk with the domain experts about the problem space to come up with ideas for the solution space.
Before our first workshop, we asked our client about their organization and which departments and roles were involved in planning roadwork. The number was surprisingly high, because it turned out that different departments were responsible for planning different types of streets. The same applied to bridges, tunnels, etc. To get to know every department and role involved, we scheduled three workshops, each three hours long. About seven domain experts from different departments participated in each workshop.
In those workshops, we asked the participants about their responsibilities. We collected their answers in a use case diagram that we projected on a wall. In one workshop, a domain expert complained: “Oh no, why do we have to model our business processes again?” He pointed at a shelf filled with folders. “Just look up what you need in our documentation!” But we had a feeling that the answers we were looking for were either not in the documentation or were buried so deep that we would struggle to find them. We assured the domain expert that we would take a look at the documentation later. After collecting some use cases and learning which ones were highly cooperative, we used Domain Storytelling to dive deeper into the domain. After a few sentences, even the skeptical domain expert realized that this was not an ordinary business process modeling workshop.
In a short time, we learned that a project manager for roadwork has dozens of factors to consider when planning their work. Every construction site must be planned in the context of all the other construction sites within a varying time frame and area. Over the course of the three workshops, we collected forty use cases and had the domain experts tell us five domain stories.
That body of acquired knowledge was sufficient for us to understand the problem space. In a fourth workshop, we presented our findings and asked, “Is that the problem you want us to solve?” The attending domain experts nodded in agreement.
The knowledge we gained from the five domain stories enabled us to talk with our client about their problem. Of course, we had to dive deeper into the domain to come up with solutions. During the workshops, the domain experts mentioned meetings and documents that play a role in coordinating roadwork. We asked for some examples and attended the meetings they mentioned. Quickly, ideas for designing the solution space came to our minds. We elaborated on these ideas with some more FINE-GRAINED domain stories and prototyping. Four months after the first workshop, we had a working software solution.
Speaking and Listening to Understand Each Other
Our experience in learning foreign languages is that you need to listen to other people speak that language. Repeat what you hear and pay attention to their feedback. Gradually, you will progress from individual words to phrases and to complete sentences. The more you speak, the faster you will learn.
With Domain Storytelling, you can employ the same principles as when you are learning a new domain language. Let domain experts tell you a domain story. While you record the domain story, you repeat what you have heard. You ask about any terms you are not familiar with.
Unfortunately, it is easy for us humans to misunderstand one another. To prevent misunderstandings, visual modeling comes into play. The domain experts can hear and see whether you understand their story correctly. Having two feedback channels is better than having one. After just a few stories, you will be able to talk about the people, tasks, tools, work objects, and events in that domain.
Back to the Leasing Example
In the case study in Chapter 8, we explored the leasing domain with the COARSE-GRAINED domain story Alphorn 1 (see Figure 8.1). We learned nouns like “contract” and also verbs like “to sign.” Then we moved on to FINE-GRAINED, PURE domain stories in the risk assessment subdomain. Many of the labels in these stories contain terms from the domain language. Let’s revisit Alphorn 4 (see Figure 9.1). While modeling, look out for words that you don’t understand. In sentence 1, for example, what exactly is a “credit rating”?
Figure 9.1 Alphorn 4: Risk assessment—FINE-GRAINED, PURE, TO-BE
Henning asks the domain expert for that subject matter—Raymond, the risk manager—for the meaning of these words. Stefan puts the answer in an annotation (see Figure 9.2).
Figure 9.2 Definition of a domain term
To learn a domain language, it’s best to focus on the PURE stories, because they are not tainted by the technical jargon that often comes with software systems. All levels of granularity can be interesting. To learn a language, you should begin with AS-IS domain stories. Later, when developing the language further, move on to TO-BE domain stories.
Domain stories are a good way to start learning a domain language. But they are usually not the only path you can follow to becoming fluent. In the next sections, we will briefly discuss techniques that complement Domain Storytelling.
Writing Glossaries
Writing a glossary is great for documenting what you have learned. But which terms should be included? Defining all terms from the domain is a tedious task, and many of those definitions will help nobody. Include only those terms that merit an explanation. With domain stories, it’s easy to spot which terms should be part of the glossary: Typically, they have a defining annotation. But, of course, names of work objects, activities, and actors can be worth an entry as well.
Depending on the modeling tool, different methods exist for extracting the glossary from a domain story.
In an analog setting, big sticky notes are a good choice. Put the term as a heading in big letters on top and then write the definition below in smaller letters, like in Figure 9.3.
Figure 9.3 A glossary in sticky notes
Put the stickies on a separated part of the wall or whiteboard. That way you can bring together the term definitions from several domain stories.
When using a digital tool, a simple spreadsheet file may be the right format. Table 9.1 with terms and definitions is the result.
Table 9.1 Excerpt from the Risk Management Glossary
Here again you can see that not only nouns are relevant. Understanding the verbs is equally important.
Maintaining a glossary can be cumbersome. We have worked with teams that kept their glossaries up-to-date by making them part of a user manual. Still, in many projects glossaries are not maintained and quickly become outdated. However, this is not necessarily a big problem. If writing the glossary helped you to learn the language, then it was worth the effort.
If you can refer to an existing glossary, then you can save some time. But do not confuse a glossary for a shortcut allowing you avoid having conversations with domain experts. After all, would you consider learning a foreign language just by reading a dictionary?
Observing How People Work
Observing how people work can be insightful for understanding a domain and thus complements Domain Storytelling. However, it would be hard to learn about a domain by just watching domain experts and not talking to them. Here is an analogy by Heinz Züllighoven:
Observing a Cook
Imagine you watch a cook who stirs a tomato sauce. You clock the time and measure that he stirs the sauce for exactly five minutes. Hence, you conclude that tomato sauce must always be stirred for five minutes. You repeat the process at home, but after five minutes of stirring, your sauce is still as watery as a tomato soup. Time was not the deciding factor. What you missed is that the cook stirred the sauce until it was of the right consistency.
There are more elaborate ethnographic methods than just silently observing domain experts. For example, you can do a contextual inquiry interview [Holtzblatt et al. 2005]. The interviewer observes the domain experts, but both also discuss the activities of the domain expert, and the interviewer shares their interpretations and insights.
Observation techniques help to discover unknown and implicit knowledge. You might notice things that the domain experts did not tell you at a Domain Storytelling workshop because it seemed too trivial or irrelevant to them. These techniques work best if you have at least some prior domain knowledge, because without context, it would be difficult to decide which activities you should observe. You would also have limited ability to interpret what you see.
Can’t We Just Read the Docs?
How about skipping modeling and learning domain language from existing documentation instead? Unfortunately, good documentation is hard to find and even harder to write. We assume that’s one of the reasons why the authors of the Agile Manifesto favor “Working software over comprehensive documentation” [Beck et al. 2001]. In some organizations, you will find process models, handbooks, guidelines, glossaries, specifications, regulations, and many other types of documents that contain domain language. In other organizations, you will find no documentation at all. At least then you don’t have the hassle of determining which documents are relevant to you and if they are still valid and up-to-date.
It can be a challenge to choose between using existing documentation and starting from scratch. What has worked for us is to first learn some domain language with Domain Storytelling and then review existing documentation. That makes it much easier to decide what to read and what to do with the information you’ve found.
Organizations Speak Many Domain Languages
When you ask a heterogenous group of people to tell you a COARSE-GRAINED domain story, you will notice inconsistencies and generalizations. The reason for this is that the participants work in different subdomains. For example, Alphorn as a company is clearly in the “leasing” domain, and we already discovered a subdomain “risk assessment” (see Chapter 8, “Case Study—Alphorn Auto Leasing Inc.”). This is a core domain of the company. That means it is at the heart of the business. Usually, you will find a rich and unique domain language within a core domain. But a leasing company also needs bookkeeping, marketing, and many other capabilities that can be considered domains in their own right. That means that the people you’ve invited speak different domain languages, although they all work for a leasing company.
Note
Organizations do not speak one unified, universal domain language!
In Stefan’s roadwork story that opened this chapter, the domain experts came from core domains. All of them planned roadwork. Their “dialect” differed a little, because some plan roads and others only bridges, but the whole workshop was about the parts of their job where they have to work together. We will give you another example from a different domain, but this time the subdomains use different languages:
Stefan’s Browser Games Story
I moderated a Domain Storytelling workshop for a company that develops a marketplace for browser games. The company’s service enables its customers to play games from several vendors, all with one account. In our first COARSE-GRAINED domain story, a new customer registered, put money into their account, and started to use one of the provided services.
The domain experts could not agree on what an “account” is and which activities are associated with it. We altered the domain story several times, but there was always someone who objected. When I asked for details about the account, we found out that there were two separate accounts for each customer. One was tied to the customer (some called it the “customer account”), and one was associated with the games (known to some as the “gaming account”). From that point on, we used two separate work object icons for the two types of accounts. Therefore, the domain experts had to be explicit about which kind of account they were talking about.
Later, distinguishing the two types of accounts was also crucial for inviting the right people to the follow-up workshops in which we wanted to model FINE-GRAINED domain stories.
In this anecdote, the term “account” turned out to have two different meanings, depending on the context (almost like a homonym). In one context, “account” refers to the billing and payment information of a customer. In another context, “account” means the behavior of the customer, e.g., which games they play. This is an important discovery! Uncovering such details will greatly improve your communication with the domain experts.
In addition to homonyms, you will also encounter synonyms—different words with the same meaning. Synonyms might originate from different subdomains.
Be careful: Even if you are so new to a domain that you need to understand things at a COARSE-GRAINED level, don’t paint with too broad a stroke. Let the domain experts give you a concrete example. That will help you (and them!) to check if terms like “account,” “client,” “customer,” “product,” etc., are used with the same meaning or not.
Having different languages in different subdomains is natural. Attempts to wipe them out and replace them with a unified language generally prove to be unsuccessful (see Chapter 10, “Finding Boundaries”). You should not attempt to deal with differences in language by building abstractions or synthesizing an artificial language. Instead, use annotations to indicate synonyms and homonyms in your COARSE-GRAINED stories. To resolve differences in language, you need to dig into the subdomains with FINE-GRAINED AS-IS stories and work out an unambiguous language that is specific for the subdomain. In Domain-Driven Design, such a language is called a ubiquitous language.
Using Natural Languages
A domain language is based on natural languages like French, Arabic, Hindi, Nahuatl, etc. The examples we have used in this book are in English only, but we would like to show you that Domain Storytelling also works with other natural languages. Let’s look at some everyday examples. We begin with an illustration in the authors’ first language1 in Figure 9.4.
1 Stefan was born in Austria and Henning in Germany.
Figure 9.4 In German: Traveling by taxi
Written German is based on the Latin script (just like English, but with the ligature ß and umlauts—look at “ä” in sentence 4). Domain Storytelling also works with other scripts2: Figure 9.5 uses the modern Persian (Farsi) script (which is based on the Arabic script and therefore written from right to left), and Figure 9.6 the Chinese script.
2 We thank Samaneh Javanbakht and Isabella Tran for translation and transcription.
Figure 9.5 In Farsi: Traveling by airplane
Figure 9.6 In Chinese: Traveling by train
Generally, you will use the natural language of the domain experts for modeling. In workshops that are comprised of people who speak different languages, there is usually a common language that can be used.
If an organization operates in several countries, there might even be several natural “business languages.” We recommend you follow the idea of the ubiquitous language and avoid translations as long as possible. Sometimes an international team might request an exception. But beware: many words cannot be translated without loss of information, shift in meaning, or at all.
Lost in Translation
Many organizations employ business analysts or requirements engineers who serve as intermediaries between domain experts and developer. These roles are often interpreted as professional “translators” who take input from domain experts and translate it to requirements that development teams can implement. Sometimes, even Scrum’s product owner [Rubin 2013] is implemented as a “translating” role rather than an “owning” role.
Good translators are hard to find. They carry a lot of responsibility. Nuance gets easily lost in translation. Translators might make assumptions and communicate them as facts, or they might not have the technical background required to ask the right questions for software development.
However, many business analysts and requirements engineers have skills that domain experts sometimes lack—like being able to articulate what is expected from a piece of software or finding the right level of abstraction. Also, many developers would not be able to get the right information from domain experts on their own.
We do not advise to have intermediaries work as translators because developers might be led to believe there is no more need for them to learn the domain language. Rather, it makes sense to use the skill set of business analysts and requirements engineers to bridge the gap between business and IT through moderation and facilitation. They should help domain experts and developers to communicate with each other.
Tip
Moderators can help the development team to become fluent in domain language.
Therefore, we suggest to add the role of a moderator to your cross-functional development team. This role can be assumed by anyone in the team who has the necessary skills. A business analyst or requirements engineer would be a good fit for that role, allowing them to integrate into the development team. The moderator’s goal is to help the development team become fluent in domain language. They do so by facilitating and teaching collaborative modeling with methods such as Domain Storytelling.
What to Read Next?
Differences in language are a good way to learn about the boundaries that exist within an organization. The contexts that are defined by different domain languages tell you more about the structure of an organization than org charts and the scope of existing software systems. Hence, domain languages can be used as a guide to split up monolithic software systems or to find a good scope for new software. This will be covered in Chapter 10, “Finding Boundaries.”
Once you are able to speak a domain language, you can talk about requirements more effectively. We will show you more ways Domain Storytelling can help you with requirements elicitation in Chapter 11, “Working with Requirements.”
The language becomes ubiquitous through being used in the source code. Which domain terms to use as names for classes, methods, functions, and variables is the topic of Chapter 12, “Modeling in Code.”
Finally, there are other collaborative modeling techniques that are helpful for learning a language (see Chapter 7, “Relationship to Other Modeling Methods”). Combining methods can sometimes be useful too. For instance, Example Mapping is a good follow-up to Domain Storytelling.