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
