Domain storytelling is a collaborative modeling method in which domain experts and developers tell stories from the domain together and record them in a simple graphical notation. Actors, work objects and activities make up the picture. The goal is direct communication instead of a game of telephone, so that users and the technical side don’t talk past each other.
Key Takeaways
- Domain storytelling replaces the classic requirements specification with a direct conversation between users and developers, because every translation step in between loses information.
- A domain story shows 10 to 20 steps at most and always describes a single scenario, so domain experts without a technical background can read the diagram right away.
- BDD test cases can be derived directly from fine-grained domain stories, because actor, activity and work object already give you the Given-When-Then structure of a Cucumber test.
- Domain storytelling doesn’t replace UML or BPMN, it complements them: UML is for communication between developers, domain stories are for communication between developers and users.
What Is Domain Storytelling?
Developers and domain experts use domain storytelling to work out together how a business domain really works. The method belongs in 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 line of work, and while they talk, the team draws the story as a diagram. The diagram acts as a mirror. It shows right away whether what was heard was understood correctly.
Henning Schwentner places the method firmly in the agile camp. Instead of a specification written up front and thrown over the fence, it relies on a conversation that no written document can replace.
Why a Requirements Document Isn’t Enough
Written requirements alone leave too much room for misunderstanding. That’s why domain storytelling relies on direct communication between users and developers instead of a chain of translation steps.
The underlying problem is the classic game of telephone. The user tells the business analyst, the business analyst tells the architect, the architect tells the developer. Information gets lost at every step. In the end, you get something that has little to do with what was originally needed.
The method takes the people in between out of the translator role and makes them facilitators. The requirements engineer, business analyst or architect no longer translates. Their job is to make sure the conversation happens directly, from start to finish.
How a Domain Storytelling Session Works
A session usually starts at a coarse level and then works its way into the details. First comes the big picture, then individual subprocesses get a closer look.
At the start, you invite a lot of people, just to get a grip on the domain. For a train journey, that could be a passenger, a train driver and a conductor. Together they tell the big story from A to Z without getting lost in details.
From that big picture, you can draw boundaries toward subdomains and bounded contexts. Within a single bounded context, you then go deeper with fine-grained stories. Buying a ticket and checking a ticket are separate stories with different actors.
The finer stories are done in smaller groups. How a ticket inspection works concerns the passenger and the conductor, not the ticket seller. Anyone without detailed knowledge of a step doesn’t need to be in the room.
A Domain Storytelling Example: Actors, Work Objects and Activities
The notation uses stick figures, icons and arrows and turns every spoken sentence into a picture. It’s called a pictographic language, a visual language that deliberately stays lightweight.
Here’s an example: “The conductor checks the passenger’s ticket.” That becomes two stick figures, conductor and passenger, an icon for the work object ticket and an activity written along an arrow. Actor, activity, work object, in that order.
Text is part of it, but used sparingly: names for actors, roles and work objects, and above all the domain’s verbs. Those verbs are what help you learn the domain language and shape it into what domain-driven design calls the ubiquitous language. Annotations capture anything the graphical notation can’t show.
One Story, One Scenario
Domain storytelling follows the principle of scenario-based modeling: a domain story tells exactly one scenario, not every variant in a single picture. That is the key difference from many other notations.
As a rule of thumb, a story has about 10 to 20 steps. If it gets more detailed, the detailed process moves into a story of its own. So a typical session doesn’t produce one story, it produces many.
You start with the happy path. Only then come the special cases: the passenger doesn’t have enough money. The passenger misses the connection. Each of these cases gets its own picture. The reason is practical. End users didn’t grow up with conditionals, and separate pictures stay understandable for them.
Domain Storytelling and UML Solve Different Problems
UML is a medium for communication between developers. Domain storytelling is a medium for communication between developers and users. That’s the difference.
UML is powerful, but it isn’t simple. If you want to understand all of it, there’s a lot to learn, and that rules it out for non-technical users. The visual language of domain storytelling, by contrast, can be explained in five minutes, and then the workshop can start.
The two don’t exclude each other. You can derive a UML class diagram from a domain story afterwards, and use case diagrams help pull several domain stories together into an overview. The same goes for BPMN, which is also aimed at technical readers and puts several cases into one diagram.
How Domain Stories Turn into Tests and Code
Domain stories at the right level of granularity translate almost one to one into acceptance tests. That makes the method a good fit for test-driven development and behavior-driven development.
From a story, you derive a first test case, for example in Cucumber or JUnit. The different variants in the domain give you further test cases. When the granularity is right, you can read the Given and When of a BDD test straight from the story.
The order is clear: the domain story explains the test, and the test drives 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 in both object-oriented and functional style.
Which Domain Storytelling Tool Do You Need?
You don’t need a special tool, but there is one. Egon.io runs in the browser and fully supports the method, so you can build a model with mouse and keyboard.
A whiteboard works just as well. It’s usually better than a flip chart, because you can wipe things off. A combination that has proven itself: work objects and actors on sticky notes that you can move around, and arrows drawn on the whiteboard that you can redraw. The hands-on part helps, because you can push a sticky note back and forth.
It works online too, as the pandemic years showed. What you need is a good video call where everyone has their camera on, because body language and visual feedback matter. A virtual whiteboard such as Miro lets everyone work on the model together.
Domain Storytelling Is a Tool, Not a Golden Hammer
Domain storytelling is one method among several, not the answer to every problem. If you apply it to everything, you fall for the golden hammer syndrome.
“For a nail, that’s a good idea. For a screw, not such a good idea anymore, and for a water pipe maybe even a bad one. 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 broaden out. Related techniques in collaborative modeling are Event Storming, User Story Mapping and, in the BDD world, Example Mapping.
Domain storytelling plays to its strengths when people interact and cooperate. That kind of cooperation shows up clearly in the pictures. In other kinds of domains, you can try it and then check honestly: are you getting a grip on the domain or not? If it doesn’t work, that’s the moment to take another tool out of the box, instead of falling in love with the method and riding it into the ground.
Frequently Asked Questions
What happens when requirements are passed on through multiple intermediaries?
Information is lost at every stage of translation. The user tells the business analyst, who tells the architect, who tells the developer: In the end, the result has little to do with the original need. Domain storytelling removes these roles from their translator function and gives them a facilitator role, so that the conversation between the user and the developer takes place directly.
Who should participate in a domain storytelling workshop?
That depends on the level of detail. For the initial “big picture,” invite many stakeholders (such as passengers, the train engineer, and the conductor on a train trip) so that the domain is described from A to Z. Fine-grained stories are developed with small groups: A ticket inspection involves passengers and the conductor, not the ticket agent. Anyone who doesn’t have detailed knowledge of a specific step doesn’t need to be in the room.
How long can a domain story be?
As a rule of thumb, a story comprises 10 to 20 steps. If it gets more detailed, the specific process is moved into its own story. A session therefore produces not just one diagram, but many. This limit serves a purpose: The diagram should remain readable at a glance for subject matter experts without technical training and serve as a reflection of what was discussed.
How do you represent special cases and exceptions in a domain story?
Each special case gets its own diagram. You start with the happy path, followed by the variants: the traveler doesn’t have enough money, the traveler misses their connection. Packing these branches into a single diagram would be counterproductive, because end users aren’t familiar with conditionals. Separate diagrams remain understandable to them.
Does Domain Storytelling Replace UML or BPMN?
No. UML is a medium for communication among developers, while domain storytelling is a medium for communication between developers and users. UML is powerful but requires a steep learning curve; the visual language of domain stories can be explained in five minutes. The two complement each other: A class diagram can be derived from a domain story, and use-case diagrams summarize multiple stories to provide an overview. The same applies to BPMN.
Can test cases be derived directly from domain stories?
Yes, if the level of granularity is right. The “Given” and “When” parts of a BDD test can be extracted from a story because the actor, activity, and subject of work define the structure. An initial test case is created in tools like Cucumber or JUnit, and variations within the domain generate additional ones. The sequence is clear: the domain story explains the test, and the test drives the production code.
Does domain storytelling work in a distributed setting rather than in a shared room?
Yes, as was demonstrated during the COVID-19 pandemic. A prerequisite is a good video call where everyone has their camera on, because body language and visual feedback contribute to the session. A virtual whiteboard like Miro enables collaborative work on the model. In person, a whiteboard is usually better than a flipchart because you can wipe away content.
For which domains is domain storytelling less suitable?
The method really shines when people interact and collaborate, because such collaboration becomes clearly visible in the diagrams. For other types of domains, it’s worth giving it a try, followed by an honest assessment: Are you able to get a handle on the domain or not? If it doesn’t work, switch to another tool, such as Event Storming, user story mapping, or example mapping.
