Domain storytelling
Natural language requirements are ambiguous
Storytelling is a human universal. From gathering around the camp-fire telling tales of ancestors to watching the latest television box-set, humans are inveterate producers and consumers of stories.
– Cooperation and the evolution of hunter-gatherer storytelling [1]
It’s not surprising that the most used method of documenting requirements is still natural language [2]. It just comes natural to us; not just to write down by software people, but also to review by domain experts.
As we mentioned in our last post regarding issues with requirements, natural language is ambiguous. Ambiguity means that a word or phrase has two or more meanings or interpretations [3]. This is a feature, not a bug, of natural language: ambiguous communication is more efficient [4].
Normally, a speaker and listener share enough context to resolve ambiguities. However, in the specific case of a domain expert explaining how a computer system should work to a software developer who is new to the field, this often breaks down [5].
It’s developers’ (mis)understanding, not domain experts’ knowledge, that gets released in production.
– Alberto Brandolini
And when using coding agents, it may be the LLM’s misunderstandings of the developer’s misunderstandings. Yikes, this is turning into a game of telephone!
Domain storytelling to the rescue
Domain storytelling is a collaborative modeling technique that highlights how people work together [6]. Its primary purpose is to transform domain knowledge into business software. This purpose is achieved by bringing together people from different backgrounds and allowing them to learn from each other by telling and visualizing stories:
Domain storytelling is storytelling with a twist.
Domain stories are told from the actor’s perspective. An actor can be a person, a group of people, or a software system. Actors create, work with, and exchange work objects, such as documents, physical things, and digital objects. Actors and work objects are shows as icons. The actor’s activities are shown as arrows connecting those icons.
Domain stories consist of multiple, numbered sentences. Every sentence follows a much stricter grammar than natural language: who (actor) does what (activity) with what (work object) with whom (other actor).
This limited grammar reduces ambiguity, because it forces the author to be specific (while still sounding natural).
Domain stories are written as text, but also rendered as a diagram. In general, this combination leads to better understanding [7] and makes it easier to spot any remaining ambiguity [8]. These advantages hold specifically for software requirements as well [9].
In summary, domain storytelling benefits from our special relationship with stories, which reduces a lot of the downside of using natural language to capture software requirements.
References
- Smith, D. et al. Cooperation and the evolution of hunter-gatherer storytelling, Nature, 2017.
- Franch, X. et al. The state‑of‑practice in requirements specification: an extended interview study at 12 companies, 2023.
- Fortuny, J. et al. Ambiguity in linguistics, 2024.
- Piantadosi, T. et al. The communicative function of ambiguity in language, 2012.
- Méndez Fernández, D. et al. Naming the Pain in Requirements Engineering, 2016.
- Hofer, S. and Schwentner, H. Domain Storytelling: A Collaborative, Visual, and Agile Way to Build Domain-Driven Software, 2022, Addison-Wesley.
- Lei, H. et al. Effects of Adding Illustrations to Texts on Students’ Science Achievement: A Meta-Analysis, 2025.
- Frick, P. et al. Cross-Modal Activation, Integration, and Validation When Reading Illustrated Texts: Evidence From Reading Times and Eye-Tracking, 2026.
- Popescu, D. et al. Improving the Quality of Requirements Specifications via Automatically Created Object-Oriented Models, 2007.