Domain-Driven Documentation

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.

7 thoughts on “Domain-Driven Documentation

  1. Hi Richard,

    Thanks for all the great posts. For someone like me who had been designing data driven applications for quite a few years and gradually making progress towards a better OO backed applications, your posts are real eye openers.

    I have a small favour to ask. I tried to model the domain you described in this post as an exercise and found it quite challenging due to inexperience. I am really interested to learn how you modeled this one. (I am struggling with the “A Monitored Individual is a role played by certain Employees. Each Monitored Individual is required to be proficient in a number of Competencies” part). Would you mind sharing your design?


  2. Magesh : sure no problem, let me explain with yuml. First we created an explicit domain role for a real-life role played by an Employee:

    IRole domain role

    Monitored Individual is then an instance of this role. It is played by an Employee, has a collection of required Competencies you can add/remove, and other behaviour related to recording practice of the Competencies.


  3. The synonym thing drives me nuts. Working with a client that insists on calling the same thing by different names, semi-randomly, really hinders communication.

Comments are closed.