Using draw.io to capture Domain Stories

Domain-Driven Design (DDD) is an approach to software development: a set of techniques, principles, and patterns used to aid in the development of complex systems. The term was coined by Eric Evans in his 2004 book: Domain-Driven Design: Tackling Complexity in the Heart of Software.

Collaboration through ubiquitous language

DDD places emphasis on collaboration between Domain Experts and Software Developers. During workshops, both parties work iteratively to define the conceptual model of the domain. By ‘domain’ we mean the subject area for which we are building the software system. During the workshop sessions, that take place as part of the initial system analysis phase, one of the tasks is to define a common, pervasive language or, as it is referred to in the DDD world, a ubiquitous language. Ubiquitous language is a set of terms and their relations that both the domain experts and technical experts understand. There are a number of techniques to aid this process, one of them is Domain Storytelling, developed by Stefan Hofer and Henning Schwentner.

Domain Storytelling (DS) is a technique of recording domain stories, as told by domain experts, using a Pictographic language. Domain stories are specific examples of what happens in the system. Each story describes one particular specific example of a process. Domain Storytelling differs from traditional process modeling methods, such as BPMN, in that Domain Stories only model a subset of a process. With Domain stories, we model a few things that do actually happen rather than all the things that can possibly happen in the system. DS follows the principle: a few good examples are more useful than a high-level abstraction.

After several stories are defined, the participants are able to talk about the people, activities, tools, work objects, and events in that domain.

Domain Storytelling Tools

To record a domain story in the form of a diagram you can use a whiteboard with some sticky notes. Alternatively, you can cut out some paper icons, that you can then stick onto the whiteboard and join using arrows. 

Once you draw the story on the whiteboard it is useful to re-create it in electronic form — so you can save it for later reference. To do this you can use an online tool developed by Workplace Solutions:

Domain Storytelling Modeler

www.wps.de

Confluence and Draw.io

Unfortunately, whilst WPS modeler is a great diagramming tool, it is not integrated with Confluence CMS which we use at our workplace. In order to embed a WPS modeler diagram into a Confluence page, you must export it as an image. We find this cumbersome especially when we need to modify existing diagrams already embedded in Confluence pages.

At our workplace, we have Confluence integrated with the draw.io diagramming tool. We use draw.io to record all our diagrams, including domain stories. The integration of draw.io is useful as it embeds the diagrams directly into the page. Confluence has a nice feature that lets you open the draw.io diagram directly from the origin page, which is particularly handy if you need to update the existing diagram.

In time we have developed our own syntax and icons that work well in draw.io.

Here is an example of a simple Domain Story:

Below is a list of icons that we curated from draw.io libraries (you can also create custom libraries). We use this set of icons in Draw.io to record domain stories:

Actor:

Actor

Depicts Actors in the System: such as Customer, Cashier or Order Manager. Optionally we can add a stereotype to the label of the icon, for example, the role of an actor. The stereotype is enclosed in the “<<>>”.

Actor <<Stereotype>>

System:

System

The system icon depicts Information Systems. A System can be an internal component or a 3rd party component. Either way, a System is considered to be a black box with respect to the rest of a diagram.

Artifact:

Artifact

Depicts an artifact, such as a message, a document, in general the object of an action. It is described by its name. Wherever required a stereotype can be given e.g. to describe further the artifact’s type.

Artifact <<Stereotype>>

Notes:

Note

Notes are used to describe elements of the domain story in more detail.
They are usually connected to the described element with a dotted line connector.

Entity:

Entity

This is a logical entity of the system, it has a name and optionally can have a stereotype annotated with “<<>>”. The color usually has no special meaning, it is used only for aesthetic purposes. In some cases, with more important entities of the system, a legend will be included that gives more information about an entity.

Action:

Action

A directed arrow depicts an Action described with a verb e.g. “installs” or with a preposition e.g. “in”, “to”, “from” etc. It has a start and an end. It interconnects Actors, Entities, Systems, etc. Actions are elements of the workflow and each workflow has a sequence number. The sequence numbers are incremented with each new workflow in a domain story.

A blue bubble marks the beginning of a workflow, there is only one starting action in a workflow.

A yellow bubble marks an intermediate action of a workflow, there can be many intermediate actions in a workflow.

A purple bubble marks the ending of a workflow, there is only one ending action in a workflow.

Reference:

Reference

The Reference symbol depicts a reference to another Domain Story and should contain a link to it.

Information:

Information

This symbol is used for pieces of information like notifications, alerts, messages, emails, etc. It can have some redundancies with Artifacts.

In our next story, we will demonstrate our diagrams’ syntax with a more elaborate example, as well as show you how you can copy icons and add them to your draw.io scratchpad for easy re-use.