Domain-Driven Design: Tackling Complexity in the Heart of Software

Documents Should Work for a Living and Stay Current
When I document a model in writing, I diagram small, carefully selected subsets of the model and
surround them with text. I define the classes and their responsibilities in words and frame them in
a context of meaning as only a natural language can. But the diagram shows some of the choices
that have been made in formalizing and paring down the concepts into an object model. These
diagrams can be somewhat casual—even hand-drawn. In addition to saving labor, hand-drawn
diagrams have the advantage of 
feeling
casual and temporary. These are good things to
communicate because they are generally true of our model ideas.
The greatest value of a design document is to explain the concepts of the model, help in
navigating the detail of the code, and perhaps give some insight into the model's intended style of
use. Depending on the philosophy of the team, the whole design document could be as simple as a
set of sketches posted on the walls, or it could be substantial.
A document must be involved in project activities
. The easiest way to judge this is to observe the
document's interaction with the 
UBIQUITOUS LANGUAGE
. Is the document written in the language
people speak on the project (now)? Is it written in the language embedded in the code?
Listen to the 
UBIQUITOUS LANGUAGE
and how it is changing. If the terms explained in a design
document don't start showing up in conversations and code, the document is not fulfilling its
purpose. Maybe the document is too big or complicated. Maybe it is not focused on a sufficiently
important topic. People are either not reading it or not finding it compelling. If it is having no
impact on the 
UBIQUITOUS LANGUAGE
, something is wrong.
Conversely, you may hear the 
UBIQUITOUS LANGUAGE
changing naturally while a document is being
left behind. Evidently the document does not seem relevant to people or does not seem important
enough to update. It could safely be archived as history, but left active it could create confusion
and hurt the project. And if a document isn't playing an important role, keeping it up to date
through sheer will and discipline wastes effort.
The 
UBIQUITOUS LANGUAGE
allows other documents, such as requirements specifications, to be more
concise and less ambiguous. As the domain model comes to reflect the most relevant knowledge of
the business, application requirements become scenarios within that model, and the 
UBIQUITOUS
LANGUAGE
can be used to describe such a scenario in terms that directly connect to the 
MODEL-
DRIVEN DESIGN
(see Chapter 3). As a result, specifications can be written more simply, because
they do not have to convey the business knowledge that lies behind the model.
By keeping documents minimal and focusing them on 
complementing
code and conversation,
documents can stay connected to the project. Let the 
UBIQUITOUS LANGUAGE
and its evolution be
your guide to choosing documents that live and get woven into the project's activity.