Domain storytelling
The great enemy of communication is the illusion of it.
I think we can all agree on communication is hard and especially when you want to convey something that is perfectly clear to you. One simple explanation can be the curse of knowledge, but this doesn’t help me (at least) on my next struggle to find the right words without getting frustrated first.
This kind of struggle can be mildly said interesting in most cases during personal communication, but what happens during anything related to business, like complex requirement of your next big product?
During the course of this post I want to put emphasis on visual communication, which can help to support any narrativ and ultimately provide additional help in getting understood.
|
Like many posts in this blog before, we again use my sample todo application - if you still
haven’t seen it yet you can find an OpenAPI specification here: https://blog.unexist.dev/redoc/#tag/Todo |
Simple use-cases &
Even with business requirements it is possible to start simple and one of the simplest things a user probably wants to do with our application is following:
Simple enough and perfectly straight forward, but the same can be expressed (and supported not replaced mind you) with a simple use-case diagram:
I suppose if I’d ask you for your first thoughts on this example now I’d probably get something in the range of this just adds clutter and is completely overkill for this really simple matter.
So still why do I insist this adds benefits?
Excursion: Visual perception &
We humans are really good in visual perception and a lot of information is gathered that way in literally a glimpse.
You can easily verify it on your own: How long does it take to read the single requirement vs how long do you have to look at the picture?
| There are so many sources to cite from, if you are curious about this whole topic please give Google Scholar a spin, but going further probably leads away from the point I want to make. |
Technical use-cases &
Targeting the right audience is also key here, but still adding too much technical jargon and information to a use-case kind of beats the benefit of getting everything in a quick glance.
UML might offer many niceties, but please ask yourself does the extension of the previous use-case add anything of value?
Let’s move on to a more complex use-case.
Advanced use-cases &
No creative hat on today, so I am just going to re-use an idea from my previous [logging/tracing showcase][]:
This just adds a bit more complexity, but with focus on the business side the updated use-case can look like this:
So far this probably doesn’t bring any real benefit business-wise, so let us quickly add a way to actual see the created todo entries and awestruck our competitors:
There are many more ways to improve these use-cases and I don’t lack funny ideas, but the main goal here was to demonstrate the power of visual use-cases and the story that can unfold.
Instead of creating all of these use-cases in isolation, we can also carry on with the story idea and actually tell them.
Domain-stories &
At its heart Domain Storytelling is a workshop format, usually held by a domain expert and a supporting moderator, who share examples how they actually work inside the domain.
While the expert explains the domain, the moderator tries to record the story with a simple pictographic language. Each domain story covers one concrete example and can be directly used to verify if the story has been understood correctly or otherwise adjusted.
This approach allows all participants to learn the domain language (see ubiquitous language), get an understanding of the activities of the domain and also discover boundaries between the different parts (see bounded contexts).
Show and tell &
The authors of the book Domain Storytelling [domstory] also provided Egon, a lightweight editor to support the workshop format.
One of my personal favorite features among others it the replay button to actually blend in the different steps like in a good slidedeck.
If we translate our last use-case to a simple domain story, one version could be like this:
Conclusion &
Writing and evaluating requirements can be a progressive approach as we have seen with the evolution from a single no-brainer requirement to a more complex one. Going even further, the whole process can be done in a conversational and story-telling way and directly improve the understanding of all participants.
Using diagrams for communication isn’t something new, still I rarely see developers using them. I sometimes think this might be a problem of tooling, but with the rise of documentation-as-code this shouldn’t be an excuse anymore.
Domain storytelling is a different approach to the whole idea and even if you don’t follow this approach by detail, your projects can still benefit from the way Egon tells your stories.
If you interested in this topic and want to read more about it I highly suggest to have a look at these two books:
-
Domain Storytelling [domstory]