From Writing Great Specifications by Kamil Nicieja

A ubiquitous language has to be a language that grows out of blending technological expertise with business expertise in reasonable proportions. This article discusses how to ‘distill’ business domains from the ubiquitous language of a business or project.


Save 37% on Writing Great Specifications. Just enter code fccnicieja into the discount code box at checkout at manning.com.


The “ubiquitous language” is a language cultivated in the intersection of technical and business jargons. Each project has its own ubiquitous language. It isn’t a language of the business, nor is it the language of technology. It’s a mix of both.


Figure 1. The sources of an ubiquitous language-a language created by mixing the jargons of technology and business to build a unified lingual model that can be used by both domain and technology experts.


The domain experts- who are people with authority in an area or topic-have their design jargon. The technology experts, such as designers, testers, analysts, or engineers, have their jargon. The problem is that design jargon is as bad as technical jargon. When they talk too much about their work at the dinner table, bankers can be as annoying as programmers, designers, or testers. Anyone can be difficult to understand to a layperson inexperienced in their domain when talking in professional or technical jargon. With expert technology copywriting, enterprise technology companies can overcome the barrier which prevents their content from moving the audience. Approaches that involve storytelling and understanding the need of focusing on the customer could prove handy to businesses aiming to better their business and reach their clientele. Further, for ensuring client satisfaction, businesses can incorporate real-time employee feedback software that can track the project and get the issues resolved quickly.

We shall now explore how analyzing a ubiquitous language can be used to derive a model of the business domains used within a specification suite. Deriving the model is the first step in getting to our end goal-which is to create a proper system for organizing large specification suites according to the business domain.

If we compare two projects from two different fields, they’ll have vastly different ubiquitous languages. The narrower the business domain of a project, the more difficult the language seems to outsiders. For example, most people easily understand consumer-facing aspects of many businesses. Pop culture can help, too. Movies about Wall Street made many people understand the basic finance keywords such as shorting, popularized by a 2015 movie Big Short, or IPO, an Initial Public Offering, depicted in critically acclaimed The Wolf of Wall Street movie from 2013, but that doesn’t then mean that they’re going to go and look at more information from CFO Strategies LLC, for example. People are only going to go to specific sites if they know that is what they specifically need Most businesses, such as Activitee, can only dream of similar publicity to what these movies can offer. Before we move on to continue our work on Activitee’s specification suite, let’s analyze a simpler example.


Spotting different domains in your scenarios

The ubiquitous language lies at the heart of Domain-Driven Design. Gherkin scenarios can be a great source of a ubiquitous language, because each scenario is a recording of a conversation business experts had with the technology experts about the requirements. If the recording is truthful, the scenario should easily capture a ubiquitous language which the experts created during their conversations, both face-to-face and in writing. We can imagine that a raw record won’t be perfect. Let’s say that we’re sitting in a specification workshop for a cloud storage service like Dropbox, Google Drive, Apple iCloud, or Microsoft OneDrive. A domain expert s talking. You’re writing down the behavior explained by the expert as a Gherkin draft. The record ends up on the whiteboard:

Listing 1. A conversation recorded as a Gherkin scenario

  
 Given a 2 GB limit on free cloud drive accounts
   And 2 GB of files on Simona's free cloud drive account
  When she upgrades to the premium plan
  Then her credit card should be charged $5
   And her storage should be upgraded to a 40 GB limit
  

It’s a good enough draft-at least for the brainstorming stage. If we look at the scenario more closely, we’ll see that it introduces terms from several domains into a ubiquitous language of our team

  • words like cloud drive are from the cloud domain

  • gigabytes, files, or storage are from the more general storage domain, which, nonetheless, must stay connected to the cloud domain

  • and words like premium plan, free, or credit card are from the payments domain or commercial offering domain, a domain that all non-free products share

In fact, we could easily map how different domains map onto our scenario.


Figure 2. Different domains can appear in a single scenario depending on how we formulate the behavior using a ubiquitous language


We can notice that some of these domains don’t have to be tightly-coupled. For example, the payments domain doesn’t have to be connected closely to the storage domain. Upgrading your account to the premium plan will make other non-storage features, such as team collaboration, available, too-maybe we should look for a more general way to specify the details of our business model. But that doesn’t mean we can uncouple all domains. The storage domain, for example, often stays connected to the cloud domain, because there can be no cloud storage without any storage in the first place.


Building a domain-driven specification suite in practice

We can now get back to our Activitee example. In this section, we’ll try to derive domains from a few specifications for Activitee. Thanks to the distillation process, we’ll be able add another layer to our suite-building skills and organize Activitee’s specifications and actors by their subdomains.

NOTE

Domain-driven specification suite-A specification suite organized according to its various domains. Domain-driven suites are easier to manage when we’ve got too many actors or when our actors have too many Abilities.


Distilling subdomains from unequivocal scenarios

We shall begin with an easy and unequivocal example. Here’s an Ability which specified how employees can authenticate and manage their identity on the Activitee platform (see listing 2).

Listing 2. features/abilities/security/employees/authentication.feature

  
 Ability: Employees can authenticate and manage their identity
  
   Scenario Outline: Users should be able to use two-factor authentication
  
     Given  for Simona
       And Simona's desire to log in
      When she provides her username
       And she provides her password
       And she enters 
      Then she should be 
  
     Examples: Two-factor authentication
       | authentication | code | authenticated |
       | two-factor auth | correct code | logged in |
       | two-factor auth | wrong code | not logged in |
  
     Examples: Make sure single-factor authentication still works
       | authentication | code | authenticated |
       | traditional auth | no code | logged in |
  
   Scenario Outline: Users should be able to review their login history
  
     Given Simona's previous logins were from 
      When somebody logs in to her account from 
      Then her account should be considered 
       And Simona should be notified about the security breach
  
     Examples:
       | country | login | compromised |
       | the USA | the USA | secure |
       | the USA | the UK | compromised |
       | the UK | the UK | secure |
       | the UK | the USA | compromised |
  
   Scenario: Users should be able to log out remotely
  
     Given Simona was notified about the security breach
      When she confirms her identity via two-factor identification
      Then she should be able to log herself out from all devices remotely
  

The three scenarios from listing 2 are focused. They talk about one thing and one thing only-the topic of security (see table 1). Their business context explains that. They were created when Activitee signed a new client who had an active Chief Information Officer responsible for the information technology and computer systems used in their company.

Table 1. Domains in listing 2

Domain

Ubiquitous language

Security

authentication, two-factor authentication,

password, compromised account, secure,

security breach, identity, remote log out

Specifications like this are easy to analyze, because they're unequivocal. We can derive the domain easily as the scenarios only talk about a single topic. If all Gherkin specifications maintained this one-to-one relationship between scenarios and domains, our job in this section would almost be done. Unfortunately, as we saw in figure 2 and as we'll see in the paragraphs to come, reality isn't always organized this neatly.


Distilling subdomains from mixed scenarios

Here are some specifications that allow HR representatives to target their programs to specific audiences to allow engineers to see different events than sales representatives, as their interests may differ (see listing 3).

Listing 3. features/abilities/events/HR/targeting.feature

  
 Ability: HR reps can target wellness programs by choosing specific audiences
  
   Scenario: Managing participants based on selected people
  
     Given Mike drafted a new event
       And he chose to invite only selected participants
      When he invites Simona for an annual review
      Then only Simona should be notified
       But other employees such as Jane should not be notified
  
   Scenario: Managing participants based on their location
  
     Given Mike drafted a new event
       And he chose to invite only selected participants
      When he invites employees from Atlanta
      Then employees in all departments from Atlanta should be notified
       But employees from New York should not be notified
  
   Scenario: Managing participants based on their department
  
     Given Mike drafted a new event
       And he chose to invite only selected participants
      When he invites employees from Engineering
      Then employees in all locations who work in Engineering should be notified
       But employees who work in Sales should not be notified
  
   Scenario: Managing participants based on their location and department
  
     Given Mike drafted a new event
       And he chose to invite only selected participants
      When he invites the Engineering team from Atlanta
      Then employees in the Engineering team in Atlanta should be notified
       But employees who work in Engineering in New York should not be notified
       And employees who work in Sales in Atlanta should not be notified
       And employees who work in Sales in New York should not be notified
  

Table 2. Domains in listing 3

Domain

Ubiquitous language

Event

event, draft, invite, participants, annual review

Organization

employee, team, location, department

The language in the four scenarios from listing 3 isn't as unequivocal as in the previous specification we analyzed (see table 2). At least two domains can be derived from our new steps. Some domain concepts refer to the events domain, and others to the domain of organization.

If we only wanted to analyze the ubiquitous language of our specification suite, saying there are two distinct domains at play here would be fine. The problem is that we want something different. We want to organize the suite by its domains. As the file system is a hierarchic structure, we'll only be able to assign the feature file including the Ability from listing 3 to a single domain (if we want various directories to represent various domains). Therefore we must choose between the two domains we've distilled.

We can make our choice based on multiple approaches:

  • we can treat the core domain as more important than other subdomains

    • in Activitee's case the events domain is clearly the core domain

    • the downside of this approach is that the core domain would always take precedence in every scenario it appears in-which isn't something we'd want, as most scenarios must deal with the core domain in some way or another

  • we can count the domain concepts (words) in each domain and assume that the more popular domain is also more important

    • the first downside is that we've no guidelines for dealing with draws

    • the second downside is that some domains will be more popular only because they're more generic than others or because they've more non-functional aspects, making it easier for them to spread horizontally across the suite

  • we can combine the two previous approaches to "calculate" relative weight of each domain

    • this way, we acknowledge that some domains (such as the core domain) are inherently more important than others

    • but we also acknowledge that domains with more domain concepts present can, in some cases, be more essential than even the core domain

Table 2 shows that the specification from listing 3 is close to a draw, with a 5-4 result. We can assume that both distilled domains are almost equally important to our distillate. Personally, I'd recommend choosing the events domain because the scenarios talk only about managing participants and the core domain can take precedence in this case. Let's talk about an example when the opposite would be true. This specification says that employees should only see Activitee content which is relevant to them-and that the relevancy should be calculated based on their branches and departments (see listing 4).

Listing 4. features/abilities/organization/employees/news feed.feature

  
 Ability: Employees can see content they like in the news feeds for their branches
  
   Scenario Outline: Employees should only see content relevant to them
  
     Given  from  who works in 
      When  looks at the company dashboard on Activitee
      Then  should see  
  
     Examples: Employees should see after-work content only from their location
       | person | branch | department | type | content |
       | Jane | New York | Engineering | New York after-work | events |
       | Mike | New York | HR | New York after-work | posts |
       | Tom | Atlanta | Sales | Atlanta after-work | events |
       | Ramona | Atlanta | Engineering | Atlanta after-work | posts |
  
     Examples: Employees should see work-related content from all locations
       | person | branch | department | type | content |
       | Mike | New York | HR | Atlanta HR | events |
       | Jane | New York | Engineering | Atlanta engineering | posts |
       | Jane | New York | Engineering | New York engineering | events |
       | Tom | Atlanta | Sales | Atlanta sales | events |
       | Ramona | Atlanta | Engineering | Atlanta engineering | posts |
       | Ramona | Atlanta | Engineering | New York engineering | events |
  

Table 3. Domains in listing 4

Domain

Ubiquitous language

Events

events, after-work, work-related

Organization

employee, branch, department, location, posts

NOTE

I counted posts as a part of the organization subdomain because Activitee's news feed treats posts as pieces of content published in various interest groups-and groups belong to the organization domain.

If we have a look at table 3, we'll see that listing 4 is the opposite of listing 3. We're close to a draw again-but this time, it's a 4-5 result in favor of the organization subdomain. This, and the fact that the examples talk not only about events, but also posts in interest groups, encourages me to recommend adding this specification to the organization subdomain. Here's how that might look:


Figure 3. how the domains organize the files in the specification suite

That's all for this article. Hopefully this has been a thought-provoking read on deriving business domains from ubiquitous language.


If you want to learn more about the book, check it out on liveBook here and see this Slideshare presentation.