Who doesn’t love a good story?

Humanity has undergone tremendous changes from the times we were living in caves but one thing stayed the same: we are still very much a storytelling animal. While our ancestors told stories crammed around the fire in their caves, we tell them in bars, at the gym, and at work. They are a powerful vehicle to convey meaning.

So why not use this tool that is so deeply rooted in our evolution when it comes to tackling the old problem of bridging the gap of misunderstanding between the domain experts and the technical people? Why not use stories to transfer the domain knowledge from the domain experts to the technical people?

Domain Storytelling

Enter Domain Storytelling, a collaborative modeling technique based on having people from different backgrounds learning from each other by telling and visualizing stories.

It originates from the University of Hamburg but it was refined and made popular by two Germans named Stefan Hofer and Henning Schwentner.

The Pictographic Language

Domain stories are based on pictographic language and are told from the Actor’s perspective. An actor can be a person, group of people or a computer system. They play an active role in domain stories and are represented by icons:

Actors create, work, and exchange work objects. They can be both physical objects like a notebook or non-physical like spoken word or an email. The exact work object we’ll have and the icons used to represent them will vary between domains.

With actors as subjects and work objects are objects of our sentences, the only thing we still need is actions (represented by arrows) to connect the two:

This sentence reads: A bride (actor) sends (action) invitations (work object) to attendees (actor). A story is usually composed of more than one sentence, so we annotate actions to establish their sequence in a story.

Now that we know how to form sentences, let’s tell our first domain story!

A cinema story

Meet Marie. She runs an art-cinema in Berlin which movie buffs are crazy about. It’s antique look and feel is part of its appeal but Marie would like to modernize it a bit nevertheless. Her friend Hans happens to be a software developer and one day, as they’re enjoying their favorite beverage on a vibrant Berlin street, they agree that Hans is going to make her a movie app.

The next day Hans comes and they start a little Domain Storytelling session.

Hans: Tell me who sells the tickets.

Marie: Well, usually the working student does it, but, you know, it’s a small cinema so sometimes I do it myself…

Hans: Ok, but what I’m interested in is what is the role you have when you are selling the tickets.

Marie: Oh. I’d say a Cashier.

Now Hans can draw the first domain actor, a cashier.

The next thing Hans wants to know is the domain-specific term Marie uses to refer to the people who are buying the tickets.

Hans: What do you call the people who buy the tickets?

Marie: We call them movie-goers. One without a subscription. I mean, most of them don’t have a subscription, if they have then it’s another story…

Hans draws another actor, a movie-goer with an annotation saying “without a subscription” because, at this point, he wants to go on with the story, and later they can revisit this special case (and maybe make a separate domain story for it).

So Hans continues.

Hans: And how do you buy the tickets?

Marie: Well, you tell the cashier the number of tickets and the show you want to see.

Hans can now connect the movie-goer and the cashier:

Hans: And then what happens?

Marie: Then the cashier suggests the best available seats.

Hans: Ok, but how do they do that?

Marie: Well, they search for the available seats in the seating plan.

Now, Hans can finish the sentence now by adding two more actions:

This conversation between Hans and Marie will go back and forth, eventually leading them to a full domain story looking something like this:

About stories

Looking at the full story you may have noticed actors only appear once. Working objects, on the other hand, can appear multiple times — once per activity. One reason for this is purely practical, as it will make drawing and following the story easier. But there is another more important reason for this. Working objects may change their status or representation during the course of the story. A seating plan, for example, can be a physical piece of paper in one action and an email in another. In that case, you would use different icons to display the different representations of the same work object.

Conditionals are not part of Domain Storytelling. If you remember, when Marie pointed out that ticket sales differ for movie-goers with a subscription, Hans documented it as an annotation. You want to model the most important alternatives in your domain as separate stories. So if movie-goers with subscription make up an important alternative in the Cinema domain, then Hans would draw a separate story for them. In general, you want to gain an understanding of the story before going in “deep” and collecting rules on all that can possibly happen in it.

Domain stories can differ in scope. For our Cinema example, we could have a high-level story like this one:

Box office ticket sale here is represented as a single action. As we saw, we can develop it into a full domain story, a more coarse-grained one.

The workshop

For the workshop to be successful it’s crucial to have the right people. In the case of our Cinema, Marie had a pretty good understanding of all parts of the domain, but for non-trivial domains, you need more than one person. And you want the people who are there “in the trenches” doing the work, not people who “know” how things are done from hearsay. Think individual contributors instead of managers.

A moderator needs to keep the participants engaged and the story going by asking questions like “What happens next?” or “Where do you get this information from?” and so on.

Active listening is a vital part of the moderator’s job. Retelling the sentences, especially after drawing them, to be sure everyone’s on the same page.

Modeling tools

When it comes to modeling tools, there are no strict rules. A whiteboard, some sticky notes, and markers are an obvious first choice.

Bear in mind, if you’re not very artistry articulated it can look a bit messy, which is why Stefan and Hennig recommend making your own little DIY-Domain Modeling kit. Print the icons beforehand, laminate them and glue a magnet on the back. This makes them reusable and the whole story less messy.

You can also opt for digital tools, such as a digital blackboard or an iPad with some general-purpose drawing tools hooked to a projector.

There is also a web browser tool made by Stefan and Hennig that you can use for a remote session or possibly for in-person sessions as well.

Bridge the gap

Bridging the gap of misunderstanding between the domain experts and technical people is vital for the success of your software and storytelling is one of the tools that can help to overcome these misunderstandings, so try it out!

“It’s developers’ (mis)understanding, not expert knowledge that gets released in production.” — Alberto Brandolini