Domain storytelling - Understanding the user

Domain storytelling is a method from the field of collaborative modeling in which technical experts and developers jointly tell stories from the domain and record them in a simple graphical notation. Actors, work objects and activities form the picture. The aim is direct communication instead of silent mail in order to avoid misunderstandings between users and technology.

Key Takeaways

• Domain storytelling replaces the classic requirements specification model with direct conversation between users and developers, because every translation stage in between loses information.
• A domain story shows a maximum of 10 to 20 steps and only ever describes a single scenario, so that experts with no technical background can read the diagram immediately.
• BDD test cases can be derived directly from fine-grained domain stories because the actor, activity and work object already specify the Given-When-Then structure of Cucumber tests.
• Domain storytelling is not a substitute for UML or BPMN, but complements them: UML communicates between developers, domain stories between developers and users.

What is domain storytelling?

Domain storytelling is a method used by developers and subject matter experts to jointly understand how a specialist domain really works. It is part of the collaborative modeling toolbox and combines two ingredients: a workshop format and a graphical notation.

The basic idea is simple. Users tell a story from their domain, and while they tell it, the team records this story as a diagram. The diagram serves as a mirror. It immediately shows whether what has been heard has been understood correctly.

Henning Schwentner clearly classifies the method as agile. It is not about a set of specifications that is created at the front and thrown over the fence. It is about a conversation that cannot replace a written document.

Why is a requirements document not enough?

Written requirements alone leave too much room for misunderstandings. Domain storytelling therefore relies on direct communication between users and developers instead of a chain of translation steps.

The problem behind this is the classic silent post effect. The user tells the business analyst, the business analyst tells the architect, the architect tells the developer. Information is lost at every step. The end result is something that has little to do with the original requirement.

The method takes the mediator roles out of the translator function and puts them in a moderator role. The requirements engineer, business analyst or architect no longer provide the translation, but rather ensure that a conversation takes place directly from start to finish.

How a domain storytelling session works

A session typically starts with a rough outline and then works its way down to the details. First a big picture is created, then individual sub-processes are examined in more detail.

At the beginning, many participants are invited in order to capture the domain in the first place. For a train journey, this would be a passenger, a train driver and a conductor. Together, they tell the big story from A to Z without getting lost in the details.

From this big picture, boundaries can be drawn in the direction of subdomains and bounded contexts. Within a single bounded context, you then go deeper, with finely granular stories. Buying tickets and checking tickets are separate stories with different actors.

The finer stories are done with smaller groups. How a ticket inspection is carried out concerns the traveler and the conductor, not the ticket seller. If you don’t have detailed knowledge of a step, you don’t need to be in the room.

This is what the graphic notation looks like

The notation works with stick figures, icons and arrows and translates every spoken sentence into a picture. It is called pictographic language, a visual language that deliberately remains lightweight.

An example: “The conductor checks the passenger’s ticket.” This becomes two stick figures, conductor and traveler, a work object for the work object ticket and an activity written on an arrow. Actor, activity, work object, in that order.

Texts are included, but sparingly. Names for actors, roles and work objects, but above all the technical verbs. It is precisely these verbs that help to learn the technical language and form the ubiquitous language, as it is called in domain-driven design. Annotations capture everything that the graphical notation does not depict.

One story, one scenario

Domain storytelling follows the principle of scenario-based modeling: a domain story tells exactly one scenario, not all variants in one picture. This is the key difference to many other notations.

As a rule of thumb, a story comprises around 10 to 20 steps. If it gets more detailed, the detailed process moves into its own story. A typical session therefore does not produce one story, but many.

You start with the happy path. Only then do the special cases follow: The traveler doesn’t have enough money. The traveler misses the connection. Each of these cases has its own picture. The reason is pragmatic. End users have not grown up with conditionals, separate screens remain understandable for them.

Domain storytelling and UML solve various problems

UML is a medium for communication between developers, domain storytelling is a medium for communication between developers and users. This is precisely where the difference lies.

UML is powerful, but not easy. If you want to fully understand it, you have to learn a lot. It is not suitable for non-technical users. The visual language of domain storytelling, on the other hand, can be explained in five minutes, after which the workshop can begin.

The two approaches are not mutually exclusive. A UML class diagram can then be derived from a domain story, and use case diagrams help to bring together several domain stories as an overview. The same applies to BPMN, which is also intended for technical readers and packs several cases into one diagram.

How domain stories are turned into tests and code

Domain stories of the right granularity can be translated almost one-to-one into acceptance tests. The method therefore fits well with Test Driven Development and Behavior Driven Development.

An initial test case is derived from a story, for example in Cucumber or JUnit. The different variants of a domain result in further test cases. The Given and When of a BDD test can be read directly from the story if the granularity is right.

The order is clear: the domain story explains the test, the test cuts the production code. In the book on domain storytelling, a chapter called “Modeling in Code” shows how to find the right granularity, derive BDD test cases and implement them both object-oriented and functionally.

What tools do you need for a workshop?

You don’t need a special tool, but there is one. Egon.io runs in the browser and fully supports the method so that a model can be created using a mouse and keyboard.

A whiteboard works just as well. It is usually better than a flipchart because content can be erased. A tried and tested combination: work objects and actors on sticky notes that can be moved, arrows on the whiteboard that can be repainted. The tactile element helps because a sticky note can be moved back and forth.

This also works online, as we have seen during the coronavirus pandemic. The prerequisite is a good video call in which everyone has their video on, because body language and visual feedback play a role. A virtual whiteboard like Miro makes it possible to work together.

Domain storytelling is a tool, not a golden hammer

Domain storytelling is one method among several, not the solution for every case. Those who apply it to everything fall prey to the golden hammer syndrome.

It’s a good idea for a nail, not such a good idea for a screw and perhaps even a bad idea for a water pipe. It’s the same with modeling tools.

• Henning Schwentner

It makes more sense to build up a toolbox: start with one tool, gain experience and then expand. Related techniques in collaborative modeling are event storming, user story mapping and, in the BDD environment, example mapping.

Domain storytelling playstest its strength when people interact and cooperate with each other. Such cooperation is clearly visible in the images. In other types of domains, you can try it out and test it honestly: Do you get a grip on the domain or not? If it doesn’t work, that’s the moment to get another tool out of the box instead of falling in love with the method and riding it to death.