Building Better Software: The Role of Domain Storytelling in DDD
Gone are the days where you were working at a product company as a software developer and you embarked into a new project guided solely by a list of requirements that you were given. Essentially, you had nothing more than a series of sentences attempting to explain the expected functionality and limitations of your system. There was no comprehension of the problem you were about to address or the user’s pain points that your project aimed to alleviate.
These projects usually ended up in back-and-forth conversations with Product to really try to understand the behavior desired and get to know what could be the edge cases, resulting in unproductive meetings and time-wasting.
That is the problem that Domain Driven Design came to the software world to solve. DDD is a set of techniques to be used in order to approach problems effectively and being able to solve them with business software efficiently.
In this article I am not going to explain you what is DDD, as I assume that if you are reading this, it is because you already have some context. With DDD the scenario described at the beginning looks totally different. DDD’s goal is to have all domain experts speaking the same language (Ubiquitous Language) and have them share the same knowledge about the problem. So you, as developer would be able to speak directly with the rest of stakeholders, PMs, business analysts, etc using a common way to communicate with.
The Shared Model A.K.A Domain Model, is basically the shared knowledge across the different Domain Experts of the company. This model includes the pain points of your users, the shared language across everyone and the understanding of how the user feels and what problem to solve.
This shared language technically called “ Ubiquitous Language” is achieved through meetings altogether discussing the terms and the different points of views of the stakeholders and it is going to be the base used for modeling your domain.
After having a common language shared across the team, then is when Domain Storytelling comes into play. Domain Storytelling is a collaborative technique to transform domain knowledge into business software. It is a way to translate all that knowledge from each of the stakeholders into entities, relationships, contexts, … and eventually into lines of code.
Getting Started
Let’s begin explaining how to implement Domain Storytelling in any problem you are facing in your company.
The first step is, of course, gather all stakeholders in a room or an online call, so that you start building and sketching drawings and diagrams together. Once you have everyone in the same room, you should start sharing your point of view and knowledge about the problem so that everyone else learns a bit more about it.
Afterwards, the drawing part begins. But not any kind of drawing, we don’t want to start drawing technical diagrams that are influenced by database relationships or programming languages. We, developers, already have a language to sketch diagrams with. UML is a great modeling language, don’t get me wrong, but you don’t want somebody from product get bored with your fancy technical diagrams. You want to use something more understandable for everybody from business analysts to PMs. And the way you are going to draw these “canvas” is by telling stories. Yes, you read it right, you want to be able to express a flow by telling a story (i.e. The user goes to the supermarket and grabs a bag of potatoes. Then, the user goes to the cashier and pay for the bag).
The stories are created based on diagrams that I am going to show you how to sketch. These diagrams use a particular set of symbols that together build up what is called the “Pictographic Language”. This language is composed of 4 elements:
- An “actor”
- A “work object”
- An “action”
- A “sequence number”
So for example, “A client signs a contract” would be represented like:
There exists a few guidelines in the pictographic language. One of them is that actors are never repeated despite being able to do more than 1 action. However, working objects should be repeated for every action done on them.
Another guideline that is a bit surprising is that in the pictographic language, if/else conditionals do not exist and that leads it to be an scenario-based language.
Basically, you need to draw a diagram specifying which scenario you are describing. For instance, imagine you are describing how a client purchases a ticket for watching a movie at the cinema. You could have many scenarios like:
- Best case scenario — happy path
- Scenario where the client pays with card and it gets rejected
- Scenario where the client pays with the exact amount of cash
- Scenario where the client pays with cash more than the amount
You get the point.
Also, the pictographic language is scope-based, that is, it depends on the scope used to sketch the diagram. There exists 3 scopes to consider when starting to sketch a diagram:
Granularity — The level of detail used to represent the story in the diagram. You can go as much into detail as you want but the more detailed you are, the more scenarios you will get.
Point in Time — Used to specify the point in time the process that you are describing is in. You could represent a flow based on how it is done right now, how it used to be, how you wished it was like, …
Domain Purity — How digital you want it to be. Let me explain it with an example. Let’s imagine again the scenario for a client purchasing a movie ticket. The diagram using a pure scope will describe how the user buys the ticket inside the ticket office in the movie theater, while the other end describes how the user grabs the laptop and goes to the movie theater’s website to purchase the ticket.
Time to Draw
Now that we know about the pictographic language, you should start the workshop and try to work on specific processes of your user. Beforehand, you should discuss the scopes taken for sketching the diagrams.
Let’s look at a practical example. We wake up one day and we decide to go the car dealership and get a new car. The problem is that you are not rich, and you cannot afford to pay the car on a single payment. Therefore, you need to ask for a contract in which you can pay in X installments. Basically the flow will look like this using pictographic language:
As you can see, we only used the 4 elements described above. With those 4, we are capable of describing the whole flow. Obviously we haven’t gone too much into detail and this is using a pure scope.
Once we have drawn this diagram, it is time to start identifying the bounded contexts. In this case we could split it into 2 BC: “Risk Assessment” and “Sales”.
As we can see in the diagram, we have the working object “Contract” that could be an entity, which has different actions. One of them in the right is to vote them, and in the left one to sign it. This gives us a hint that one and the other are indeed different and therefore should be splited and created in both contexts.
From here, you should start applying this to all your flows and start redacting more domain stories.
How to structure the diagram
The way to structure the diagram in a piece of paper is as follows:
A practical example for the flow “A client buys popcorn in the movie theater” would look like this:
See how in the right part of the paper, I note some assumptions as well as scopes considered.
Notes
- Domain Storytelling is an alternative to the classic methodology of Event Storming. Both of them being pretty similar. More here https://www.lucidchart.com/blog/ddd-event-storming
- This is just an introductory article on the topic, based on personal learnings about the matter.
- If you are more interested in learning more about this technique you should definitely check the book “Domain Storytelling: A Collaborative, Visual, and Agile Way to Build Domain-Driven Software”
- Some of the diagrams and images were taken from https://domainstorytelling.org/ . You should definitely check their site out.
