Cyrille Martraire (@cyriux on Twitter) is CTO, co-founder, and partner at Arolla (@ArollaFr on Twitter), the founder of the Paris Software Crafters community, and a regular speaker at international conferences. Cyrille refers to himself as a developer, since he has designed software since 1999 for startups, software vendors, and corporations as an employee and as a consultant.

He has worked and led multiple significant projects, mostly in capital finance, including the complete rewriting of a multilateral trading facility of interest rate swaps. In most cases he has to start from large and miserable legacy systems.

He’s passionate about software design in every aspect: test-driven development, behavior-driven development, and, in particular, domain-driven design.

Cyrille lives in Paris with his wife, Yunshan, and children, Norbert and Gustave.

Introduction

Chapter 1: Rethinking Documentation

A Tale from the Land of Living Documentation

Why This Feature?

Tomorrow You Won’t Need This Sketch Anymore

Sorry, We Don’t Have Marketing Documents!

You Keep Using This Word, but This Is Not What It Means

Show Me the Big Picture, and You’ll See What’s Wrong There

The Future of Living Documentation Is Now

The Problem with Traditional Documentation

Documentation Is Not Cool, Usually

The Flaws of Documentation

The Agile Manifesto and Documentation

It’s Time for Documentation 2.0

Documentation Is About Knowledge

The Origination of Knowledge

How Does Knowledge Evolve?

Why Knowledge Is Necessary

Documentation Is About Transferring Knowledge

Focusing on What Matters

Core Principles of Living Documentation

Reliable

Low Effort

Collaborative

Insightful

How Ants Exchange Knowledge: Stigmergy

Most Knowledge Is Already There

Internal Documentation

Internal Versus External Documentation

Examples of Internal and External Documentation

Preferring Internal Documentation

In Situ Documentation

Machine-Readable Documentation

Specific Versus Generic Knowledge

Learning Generic Knowledge

Focusing on Specific Knowledge

Ensuring Documentation Accuracy

Accuracy Mechanism for Reliable Documentation

When Documentation Does Not Need an Accuracy Mechanism

Big Questions to Challenge Your Documentation

Questioning the Need for Documentation at All

Need for Documentation Because of Lack of Trust

Just-in-Time Documentation, or a Cheap Option on Future Knowledge

Questioning the Need for Traditional Documentation

Minimizing Extra Work Now

Minimizing Extra Work Later

Making an Activity Fun

Documentation Reboot

Living Documentation: The Very Short Version

Approaches to Better Documentation

A Gateway to DDD

Domain-Driven Design in a Nutshell

Living Documentation and Domain-Driven Design

When Living Documentation Is an Application of DDD

A Story of Mutual Roots Between BDD, DDD, XP, and Living Documentation

Summary

Chapter 2: Behavior-Driven Development as an Example of Living Specifications

BDD Is All About Conversations

BDD with Automation Is All About Living Documentation

Redundancy and Reconciliation

The Anatomy of Scenarios in a File

The Intent of a Feature File

Feature File Scenarios

Specification Details

Tags in Feature Files

Scenarios as Interactive Living Documentation

Scenarios in Boring Paper Documents

A Feature File Example

A Canonical Case of Living Documentation in Every Aspect

Going Further: Getting the Best of Your Living Documentation

Property-Based Testing and BDD

Summary

Chapter 3: Knowledge Exploitation

Identifying Authoritative Knowledge

Where Is the Knowledge Now?

Single-Source Publishing

Some Examples of Producing a Published Document

A Published Snapshot with a Version Number

Remarks

Setting Up a Reconciliation Mechanism (aka Verification Mechanism)

Running Consistency Tests

Reconciliation on the Test Assumptions

Published Contracts

Consolidating Dispersed Facts

How Consolidation Works

Consolidation Implementation Considerations

Ready-Made Documentation

The Power of a Standard Vocabulary

Linking to Standard Knowledge

More Than Just Vocabulary

Using Ready-Made Knowledge in Conversation to Speed Up Knowledge Transfer

Tools History

Summary

Chapter 4: Knowledge Augmentation

When Programming Languages Are Not Enough

Documentation Using Annotations

Annotations as More Than Tags

Describing the Rationale Behind Decisions

Embedded Learning

Documentation by Convention

Living Documentation in Legacy Code with Conventions

Documenting the Conventions

Consistently Adhering to Conventions

The Limitations of Conventions

External Documentation Methods

Sidecar Files

Metadata Databases

Designing Custom Annotations

Stereotypical Properties

Stereotypes and Tactical Patterns

Using Meaningful Annotation Package Names

Hijacking Standard Annotations

Standard Annotation: [...] and Aspect-Oriented Programming

Annotation by Default or Unless Necessary

Handling Module-Wide Knowledge

Dealing with Many Kinds of Modules

Module-Wide Augmentation In Practice

Intrinsic Knowledge Augmentation

Machine-Accessible Documentation

Recording Your Rationale

What’s in a Rationale?

Making the Rationale Explicit

Beyond Documentation: Motivated Design

Avoid Documenting Speculation

Skills as Pre-Documented Rationales

Recording the Rationale as an Enabler for Change

Acknowledging Your Influences (aka Project Bibliography)

Declaring Your Style

Commit Messages as Comprehensive Documentation

Commit Guidelines

Summary

Chapter 5: Living Curation: Identifying Authoritative Knowledge

Dynamic Curation

Examples of Dynamic Curation

Editorial Curation

Low-Maintenance Dynamic Curation

One Corpus of Knowledge for Multiple Uses

Scenario Digests

Highlighting the Core

Highlighting Inspiring Exemplars

Guided Tours and Sightseeing Maps

Creating a Sightseeing Map

Creating a Guided Tour

Creating a Living Guided Tour

A Poor Man’s Literate Programming

Summing Up: The Curator Preparing an Art Exhibition

Selecting and Organizing Existing Knowledge

Adding What’s Missing When Needed

Accessibility for People Who Can’t Attend and for Posterity

Summary

Chapter 6: Automating Documentation

Living Documents

Steps in Creating a Living Document

Presentation Rules

Living Glossaries

How a Living Glossary Works

An Example Please!

Information Curation for Living Documents

Creating a Glossary Within a Bounded Context

Case Study of a Living Glossary

Living Diagrams

Diagrams Assist in Conversations

One Diagram, One Story

Living Diagrams to Keep You Honest

The Quest for the Perfect Diagram

Rendering a Living Diagram

Visualization Guidelines

Example: Hexagonal Architecture Living Diagram

Case Study: A Business Overview as a Living Diagram

Example: A Context Diagram

The Challenges with Automated Generation of Design Documentation

Summary

Chapter 7: Runtime Documentation

Example: Living Services Diagram

A Matter of Augmented Code but at Runtime

Discovering the Architecture

The Magic That Makes This Work

Going Further

Visible Workings: Working Software as Its Own Documentation

Visible Tests

Domain-Specific Notation

Generating Custom Domain-Specific Diagrams to Get Visual Feedback

Example: A Visible Test When Using Event Sourcing

A Concrete Example in Code

Living Diagrams from Event Sourcing Scenarios

Introspectable Workings: Code in Memory as a Source of Knowledge

Introspecting with Reflection

Introspecting Without Reflection

Summary

Chapter 8: Refactorable Documentation

Code as Documentation

Text Layout

Coding Conventions

Naming as the Primary Documentation

Composed Methods: You Need to Name Them

Idiomatic Naming Is Contextual

Coding Against a Framework

Type-Driven Documentation

From Primitives to Types

Documented Types and Integrated Documentation

Types and Associations

Types over Comments

The Composed Method

Fluent Style

Using an Internal DSL

Implementing a Fluent Interface

Fluent Tests

Creating a DSTL

When Not to Use a Fluent Style

Case Study: An Example of Refactoring Code, Guided by Comments

Integrated Documentation

Type Hierarchy

Code Searching

Semantics Derived from Actual Usage

Using Plain-Text Diagrams

Example: Plain-Text Diagrams

Diagrams as Code

Summary

Chapter 9: Stable Documentation

Evergreen Content

Requirements Are More Stable Than Design Decisions

High-Level Goals Tend to Be Stable

A Lot of Knowledge Is Less Stable Than It Looks

Case Study: A README File

Tips for Evergreen Documentation

Avoiding Mixing Strategy Documentation with the Documentation of Its Implementation

Ensuring Stability

Using Perennial Naming

Organizing Artifacts Along Stable Axes

Linked Knowledge

Volatile-to-Stable Dependencies

Broken Link Checkers

Link Registry

Bookmarked Searches

Categories of Stable Knowledge

Evergreen README

Vision Statement

Domain Vision Statements

Goals

Impact Mapping

Investing in Stable Knowledge

Domain Immersion

Investigation Wall

Domain Training

Live-My-Life Sessions

Shadow Users

A Long-Term Investment

Summary

Chapter 10: Avoiding Traditional Documentation

Conversations About Formal Documentation

Wiio’s Laws

The Rule of Three Interpretations

Obstacles to Conversations

Working Collectively for Continuous Knowledge Sharing

Pair Programming