Here’s a couple of real-life documentation examples from a system I’ve been building for a client:
A Monitored Individual is a role played by certain Employees. Each Monitored Individual is required to be proficient in a number of Competencies, according to [among other things] what District they’re stationed in.
A Training Programme is comprised of Skills, arranged in Skill Groups. Skill Groups can contain Sub Groups with as many levels deep as you like. Skills can be used for multiple Training Programmes, but you can’t have the same Skill twice under the same Training Programme. When a Skill is removed from a Training Programme, Individuals should no longer have to practice it.
This is the same style Evans uses himself in the blue DDD book. A colleague jokingly called it Domain-Driven Documentation.
I adopted it after noticing a couple of problems with my documentation:
- I was using synonyms — different words with the same meaning — interchangeably to refer to the same thing in different places.
- Sentences talking about the code itself looked messy and inconsistent when mixing class names with higher-level concepts.
It’s a pretty simple system. There are only three rules to remember: when referring to domain concepts, use capital letters, write them in full, and write them in bold.
Highlighting the names of domain concepts like this is a fantastic way to hammer down the ubiquitous language — the vocabulary shared between business and developers.
Since adopting it, I’ve noticed improvements in both the quality of my documentation, and of the communication in our project meetings — non-technical business stakeholders are starting to stick to the ubiquitous language now, where in the past they would fall back to talking about purely UI artifacts. This is really encouraging to see — definitely a success for DDD.
