liveBook · Manning

Living documentation

As explained in Collaborative Software Design: How to facilitate domain modeling decisions

Documentation that is continuously revised to reflect changes in the system, model, design, or decisions it describes.

Living documentation keeps models, decisions, designs, and thought processes aligned with new information. It changes through feedback loops rather than remaining a finished record. section 11.3 section 11.3.1

Use living documentation to keep collaborative design responsive:

  • Review and adjust models collectively after each modeling iteration or walkthrough. section 11.3.1
  • Add information discovered through techniques such as Big Picture EventStorming, process EventStorming, or Example Mapping. section 11.3.1
  • Separate increasingly large online whiteboards by bounded context or concern when one board becomes difficult to manage. section 11.3.1
  • Keep decisions transparent by maintaining ADRs and enabling asynchronous comments from absent stakeholders and experts. section 11.7

From one board to an evolving map

A team may begin with one Miro board containing EventStorming, context maps, Pros-Cons-and-Fixes lists, and polarity maps. As new feedback accumulates, it can split the material across bounded-context boards and connect the evolving decisions through ADRs. section 11.3.1

Figure 11.7 Model Exploration Whirlpool from Eric Evans. This whirlpool helps in considering collaborative modeling as a collection of feedback loops, rather than a linear process. (Source: www.domainlanguage.com/ddd/whirlpool/)

Use the Model Exploration Whirlpool to frame collaborative modeling as recurring feedback loops instead of a linear process. section 11.3.1

How Collaborative Software Design: How to facilitate domain modeling decisions covers it

How deep it goes
Explains iterative updates, collective walkthroughs, documentation sources, and board organization, but stops short of prescribing a complete documentation workflow.
Examples
Uses Miro and Mural boards, EventStorming, context maps, Pros-Cons-and-Fixes lists, polarity maps, and ADRs.
What you can do after
Operate/configure evolving documentation with feedback loops, reorganized whiteboards, ADRs, and asynchronous review.
How it connects
Connects feedback loops, ADRs, collaborative modeling, EventStorming, Example Mapping, context maps, and bounded contexts.

Also explained in

Compare how 3 books explain living documentation →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Collaborative Software Design: How to facilitate domain modeling decisions. The section links point to the parts of the book it draws on.