Domain Storytelling with PlantUML

DomainStory-PlantUML uses PlantUML to describe and document a domain story which was developed in a Domain Storytelling workshop.

Table of Contents

• Getting Started
  • Basic Story Layout
  • Adding Notes or Annotations
  • Auto-Incrementing Steps
  • Basic Styling
  • Extensions
• Advanced Features
  • Dynamic Creation of Work Objects
  • Advanced Story Layout
• Advanced Samples
  • Cinema
  • Airport Bus
• License
• Acknowledgements

Getting Started

At the top of your domain story PlantUML .puml file, you need to include the domainStory.puml file found in the root of this repository.

The library is now part of the PlantUML Standard Library and may be included via

!include <domainstory/Domainstory>

If you want to use the always up-to-date version in this repository, use the following include definition

!include https://raw.githubusercontent.com/johthor/DomainStory-PlantUML/main/domainStory.puml

To be independent of any internet connectivity, you can also download the file found in the root and reference it locally with

!include path/to/domainStory.puml

After you have included domainStory.puml you can use the predefined macro definitions for the domain story actors:

• Person(name, [label], [color], [scale], [note])
• Group(name, [label], [color], [scale], [note])
• System(name, [label], [color], [scale], [note])

As well as the domain story work items:

• Document(name, [label], [color], [scale], [note])
• Folder(name, [label], [color], [scale], [note])
• Call(name, [label], [color], [scale], [note])
• Email(name, [label], [color], [scale], [note])
• Conversation(name, [label], [color], [scale], [note])
• Info(name, [label], [color], [scale], [note])

Activities between actors and involving work items are described via the activity macro:

activity(step, subject, predicate, object, [post], [target], [objectArr], [targetArr], [color], [scale], [note])

In addition to these, it is also possible to define boundaries viaBoundary(name, [label], [backgroundColor], [note]).

Now let's create our first domain story:

@startuml
!include https://raw.githubusercontent.com/johthor/DomainStory-PlantUML/main/domainStory.puml

Boundary(Party) {
    Person(Alice)
    Conversation(weather)
    Person(Bob)
}

activity(1, Alice, talks about the, weather, with, Bob)
@enduml

More information can be found here:

• Domain Storytelling
• REAL WORLD PlantUML—Sample Gallery

Basic Story Layout

For single story diagrams, a landscape orientation is preferred and is therefore the default orientation. If you combine multiple stories into a domain journey, a portrait orientation usually gives better results. The orientation can be switched via !$storyLayout = "[left-to-right|top-to-bottom]" at the top of your file.

ℹ️ Wrangling diagram elements to an exact position or layout is not what PlantUML is for.

If the default layout does not please your inner artist, there are some possibilities to improve it.

Group elements via together { elements... }. Those elements will be grouped together.

The activity macro provides two features for better layout control.

Firs the step value can be combined with a direction indicator suffix

• ^ for UP
• > for RIGHT
• v for DOWN
• < LEFT

The following activity will be directed to the left of Alice.

activity(1<, Alice, talks about the, weather, with, Bob)

More details and the second activity direction feature will be discussed in Advanced Story Layout.

Adding Notes or Annotations

All elements support adding notes via the keyword argument $note.

Boundary(wonderland, $note=like Oxford) {
  Person(Alice, $note=fizz)
  Conversation(weather, $note=buzz)
  Person(Hatter)
  activity(1, Alice, talks about the, weather, with, Hatter, $note=sunny)
}

When adding a note on an activity, the note will be added to the object of that activity.

Furthermore, the first symbol of the note text controls the orientation of it. If its one of ^, >, v or < the note will be placed above, right, below or left of its element of reference. Otherwise, it will be placed in the normal story direction of its element.

Notes may also be placed via the basic PlantUML mechanism.

Boundary(wonderland) {
    Person(Alice)
    Document(bottle)
}
note bottom of Alice : main character
note top of bottle : drink me
note right of wonderland : visit me

Auto-Incrementing Steps

The activities will be numbered by default and may keep track of the current step number automatically. Therefore, when describing activities, the current step label supports multiple special value specifications to control the behavior.

Step Value	Description	Auto Increment
_ underscore	sequential step	yes
| bar	parallel step	no
. full stop / period	hidden step counter	no
space or '' none	hidden step counter	no
n any integer	step label will be (n)	no
=n equal sign prefix	step label will be (n) and step counter will be set to that integer and auto-increment will continue from there	no

See the following example for more details step labels and auto increment

activity(_, Bob, talks about the, weather1) /' auto-increment will create step 1 '/
activity(_, Bob, talks about the, weather2) /' auto-increment will create step 2 '/
activity(|, Alice, talks about the, weather2) /' no increment will create step 2 '/
' will not create step, nor auto-increment, and will not display the step label
activity(.<, Bob, also talks about the, weather3)
activity(42, Alice, asks about all the, talking1, again, Bob) /' will create step 42 '/
activity(|, Bob, talks about the, weather4) /' no increment will still create step 2 '/
' will create step 10 and set the step counter to 10
activity(=10, Alice, talks about, talking2, Bob)
activity(_<, Bob, is embarrassed about, talking3) /' auto-increment will create step 11 '/
' will not create step, nor auto-increment, and will not display the step label
activity( , Alice, writes, mail, to, Bob)

Basic Styling

The following style definitions are used by default.

Property	Default Value	Description
$storyLayout	left-to-right	Basic direction of the activity arrows
$textColor	#0b0c10	Color of all text
$actorStyle	default	Use outlines instead of filled icons for actors
$actorScale	1	Size of all actors
$actorColor	#1f2833	Color of all actors
$objectStyle	default	Use outlines instead of filled icons for work items
$objectScale	0.8	Size of all work items
$objectColor	#1f2833	Color of all work items
$boundaryColor	#1f2833	Color of boundary borders
$activityColor	#c5c6c7	Color of the activity arrows
$stepColor	#66fcf1	Background color for step numbers
$stepFontSize	16	Font size for step numbers
$stepFontColor	$textColor	Font color for step numbers, same as $textColor
$noteColor	#c5c6c7	Background color for notes
$noteBorder	#1f2833	Border color for notes

To use your own styling, you need to define the relevant styling properties before including the library. The following example would combine green actor icons with red text.

@startuml
!$textColor = "red"
!$actorColor = "green"

!include https://raw.githubusercontent.com/johthor/DomainStory-PlantUML/main/domainStory.puml

Person(Alice)
@enduml

Extensions

If the default actors and work objects are not enough to express your specific needs, see the extensions sample for a way to add new actors and objects.

Advanced Features

These features might come handy after you've used the library for quite some time.

Dynamic Creation of Work Objects

Instead of predefining all work objects, they can also be defined on the fly when they are used. Prefix the work object with the kind of object you want to create followed by a colon e.g. Conversation:.

Additionally, you can specify the color and scale of the created work object via the keyword arguments $color and $scale

@startuml
!include https://raw.githubusercontent.com/johthor/DomainStory-PlantUML/main/domainStory.puml

Boundary(System) {
    Person(Alice)
    Person(Bob)
    activity(1, Alice, talks about the, Conversation: weather, with, Bob, $color = red, $scale = 2)
}
@enduml

⚠️ If you want your dynamically created objects to be placed inside a boundary. You need to declare the activity inside said boundary.

Advanced Story Layout

If the aforementioned lay-outing techniques described in Basic Story Layout are not enough, the activity macro supports more layout tricks.

In addition to the step counter specifications described above, the step value may also specify the direction of the activity where X is one of the specifications above.

Step Value	Description	Auto Increment
X> greate-than sign suffix	direction of activity will be to the right	depends on X
X< less-than sign suffix	direction of activity will be to the left	depends on X
Xv vee suffix	direction of activity will be downwards	depends on X
X^ caret suffix	direction of activity will be upwards	depends on X

See the tests for more details.

• activity directions for left-to-right layout
• activity directions for top-to-bottom layout
• activity directions for both layouts

Furthermore, the activity macro also provides two optional parameters, which allow you to specify the arrow orientation in full details.

• $objectArr will define the arrow direction between the subject and the object
• and $targetArr will define the arrow direciton between the object and the target.

Some possible arrow specifications are -->, ->, <-, <--, and -up->. For more details, see The Hitchhiker's Guide to PlantUML .

activity(1, Alice, talks about the, weather, with, Bob, -->, ->)

You can use underscores _ in cases where you don't have a post action, or target but want to specify the arrow orientation directly. When you specify only the arrow between subject and object, the specification will also be used for the arrow between object and target. So the following lines describe all more or less the same activity.

activity(1, Alice, talks about the, weather, , Bob, <--, <--)
activity(1, Alice, talks about the, weather, Bob, _, <--)
activity(1, Alice, talks about the, weather, _, _, <--)

If all of that does not help your layout problems, there's always the possibility to introduce hidden connections only for layout purposes. Remember that every element of your story may be referenced by its name later.

Bob ---[hidden]-> Alice

Advanced Samples

Cinema

The following example is taken from the Domain Storytelling website.

Source: cinema.puml

Airport Bus

The following example is taken from Collaborative Modelling -- Wie die Kommunikation mit den Fachexperten gelingt JavaSPEKTRUM 2/2020.

Source: airportBus.puml

License

This project is licensed under the MIT License

• see the LICENSE file for details

Acknowledgements

• C4-PlantUML an inspiration to implement a collection of domain story macros
• @dirx improved domain story macros a more refined implementation of the first version