Documentation Guide for Teams Doing Domain-Driven Design

| by Jan Stenberg Follow 34 Followers on May 27, 2013. Estimated reading time: 1 minute |

The first thing a team should do when starting a software project is to draw a context map, helping them understand what the context and their core domain are, and what other contexts they may need to interact with. The most important thing is to get a shared understanding of the domain between everyone involved in developing the software, Paul Rayner, a consultant and coach, explains as a reaction to a question what kind of documentation teams doing Domain-Driven Design, DDD, should produce.

Paul begins with the end, with understanding why we are documenting; what purpose does each document serve? Consider your audience and adapt your documentation to it. Are the readers on the technical or on the business side, is this technical or business-facing documentation? As Paul writes: ”Respect Your Audience”.
Another important question deals with time: Is this document meant to support the team now as it develops the software, or is it to support future development?

For supporting the team during development Paul suggests favouring documenting (as an on-going, just-in-time, activity) which more likely will keep the documents correct and trustworthy instead of creating a (once-and-for all) document.
For future development, Paul considers knowledge not found in code, supporting tests or other artefacts particularly relevant for documentation. Without this kind of knowledge documented, no one really knows how the system ended up the way it did; knowledge is lost.

Paul has found that agile teams often prefer a light-weight approach to describing what the system needs to do in contrast to more detailed requirements specifications. One problem with detailed specifications is that design decisions often are made too soon, with insufficient domain and technical knowledge, separating design from implementation. Paul cites Mary Poppendieck:

All too often, detailed requirements lists and backlogs of stories are actually bad system design done by amateurs.

Paul is a big fan of using BDD tools for creating living documentation for the system. He is biased towards Cucumber as a tool because of the way it encourages separation of ubiquitous language from the technical implementation.

Paul Rayner is a seasoned design coach and leadership mentor, working with DDD, BDD and lean/agile processes. At the DDD Exchange 2012 Paul held a presentation: Domain Scenarios to Drive Modelling Whirlpool

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Examples? by Yuriy Zubarev

The title of the article screams for some examples. Without them the article is nothing but a platitude.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

1 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and don't miss out on content that matters to you