BT

Documentation Guide for Teams Doing Domain-Driven Design

by Jan Stenberg on May 27, 2013 |

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.

BDD
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

Hello stranger!

You need to Register an InfoQ account or 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

Educational Content

General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2013 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT