Learn domain language.
Talk about requirements.
Tell domain stories.

Domain Storytelling

The best way to learn a language is to listen to other people speak that language. Try to repeat what you hear and mind their feedback. Gradually, you will progress from individual words to phrases and to complete sentences. The more you speak, the faster you will learn.

With Domain Storytelling you can employ the same principle when learning a new domain language. Let domain experts tell their domain stories. While listening, you record the domain stories using a pictographic language. The domain experts can see immediately if you understand their story correctly. After very few stories, you are able to talk about the people, tasks, tools, work items, and events in that domain.

Domain Storytelling

We are building a community on Slack! Join us at

Currently, you need an invitation.
Contact @hofstef on Twitter or write an email to info@domainstorytelling.org

Stay up to date by following

Your first Domain Story

Imagine you are a software developer who was tasked to develop an app for a cinema. The app should have an online reservation feature. Since you have no clue where to start, you decide to interview a ticket seller who takes reservations by phone and in person. The picture shows a graphical recording of the customer service agent’s Domain Story. To read the story, just follow the numbers:

The customer asks the ticket seller for a reservation. The ticket seller looks up the show in the ticket system. ... (you get the idea)

The pictographic language

To record Domain Stories, we need a vocabulary and pictograms that represent the vocabulary:

Domain Stories are told from an actor's perspective. Actors may be a person, a group, or a software system. Hence, we use different pictograms.

Actors create, work with, and exchange work objects and information about work objects such as documents and messages. The pictograms represent the work object’s medium.

The actor's activities are depicted as arrows.

Textual annotations are useful to document assumptions, variations and exceptions.

To add a specific meaning to a pictogram, we name it with a term from the domain language:
An actor ticket seller, a work object screen plan, an activity looks up etc.

Now we can build a sentence...

  • Every sentence starts with an actor who initiates an activity.
  • Next, you need a work object or a piece of information that the actor does something with. Choose a pictogram that represents the medium of that work object (e.g. a paper icon, an email icon or a bubble for verbal information).
  • Connect the actor and the work object with an arrow. Name the arrow according to the activity (e.g. creates, edits, sends).
  • If the activity involves another actor, draw another arrow from the work object to that actor. Often, a preposition (e.g. to, with) makes a good name for the arrow.
So the basic syntax is: subject - predicate - object.

Keep in mind that anyone should be able to read the graphical Domain Story out loud.

...and tell a story

Every actor should appear only once in a Domain Story. However, if you use the same work object in several sentences, you have to draw it several times (with different numbers and maybe with a different pictogram). By numbering the work objects, we can express in what sequence the activities occur.


We use about a dozen of Google’s Material icons that represent typical office work. Feel free to compile your own set of pictograms that fits to your domain but keep in mind:

1. Using many different icons will water down your pictographic language.
2. The icons add meaning to the story and make it “tangible”.


Feeling lost?

Most business process modeling approaches show what can possibly happen in a process:


While there is value in such "algorithmic" descriptions, for many purposes you would be better suited with some examples of what actually happens.

To paraphrase requirements engineering expert Peter Hruschka:
"Three good examples are better than a bad abstraction."

Domain Storytelling helps you to find meaningful examples of what actually happens in a business process. Maybe you noticed that the visual language does not contain any symbols for cases, exceptions and parallelism.
Instead, the context of a Domain Story is defined with assumptions:
"Let’s assume the customer calls. How do you take her reservation?"

While you record the story, additional assumptions might be necessary:
"Assuming that there are enough seats available, what do you do next?"
Important alternatives and error cases deserve their own Domain Story.
Usually, very few Domain Stories are sufficient to understand a business process. After recording Domain Stories for a few processes, you will become fluent in the domain language.


"Three good examples are better than a bad abstraction."

Peter Hruschka in Business Analysis und Requirements Engineering

Domain Storytelling Workshops

Domain Stories are developed in workshops. Participants include domain experts (often from several departments), IT experts and a moderator. The moderator communicates the purpose of the workshop. All participants contribute to the story. The moderator keeps the participant’s story going by asking questions like:


What happens next?
Where do you get this information from?
How do you determine what to do next?


The moderator helps to record the Domain Stories graphically. The story needs to be visible for all participants (e.g. on a whiteboard or projected on a screen). The participants see what gets recorded and give feedback immediately.
Once the story is finished, the moderator checks if all participants agree upon the recorded Domain Story. Objections, important variations, edge cases and so on are not dismissed but written down and may trigger another Domain Story.

Do not think of Domain Stories as documentation. Use them to dive into Domain Driven Design, or to uncover requirements for software development. Inviting the right people to the workshops is important because the primary goal is to learn and communicate. A picture of a Domain Story serves as an aid to memory for those present at the workshop, but it is not a replacement for participating.



You can visualize Domain Stories with tools like PowerPoint, Visio, yEd or any other graph editor. But often a whiteboard is all you need.


Whiteboard Kit


To speed up the recording process, we developed a whiteboard kit.
You can download this template and make your own kit.

A legacy tool for Domain Storytelling’s predecessor is available at austria.omilab.org (German only).


Domain Driven Design

Since Eric Evans coined the term Domain Driven Design (DDD), an ever growing DDD community builds software that reflects its domain:

  • Developers and users talk together in domain language (or ubiquitous language as it is called in DDD).
  • The software system is shaped after the domain. Terms and relations of the domain become classes and architecture.

Strategic Design

When we want to apply DDD, we must first master the domain. We have to identify bounded contexts and work out their ubiquitous languages. This is an incremental process. As we learn more about a domain and refine our languages, we will redraw the boarders of our bounded contexts.

Domain Stories help us to understand a domain, to identify what is core, to segregate bounded contexts, and to constitute ubiquitous language.

Segregating Bounded Contexts - one of the most difficult tasks in DDD

A short history of Domain Storytelling



At Hamburg University, cooperation pictures are created as a requirements engineering method. Cooperating actors and their work objects are visualized with pictograms.



A University spin-off (now WPS – Workplace Solutions Ltd.) adapts cooperation pictures to visualize workflows. The method is used in dozens of projects under the name exemplary business process modeling.



Based on the adoxx.org modeling toolkit, WPS releases a free tool for enterprise modeling. Cooperation pictures are augmented with a glossary, use cases, org-charts, process landscapes, and IT landscapes. The current version is from 2016 (German only).



DDD enthusiasts at WPS boil down the approach and add a catchy name to it: Domain Storytelling.