Living Documentation

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: @Aspect 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

    Cross Programming

    Mob Programming

    The Three Amigos (or More)

    Event Storming as an Onboarding Process

    Knowledge Transfer Sessions

    Continuous Documentation

    Truck Factor

Coffee Machine Communication

Idea Sedimentation

Throw-Away Documentation

On-Demand Documentation

    Just-in-Time Documentation

    Provoking Just-in-Time Learning Early

    Astonishment Report

    Including Some Upfront Documentation

Interactive Documentation

Declarative Automation

    Declarative Style

    Declarative Dependency Management

    Declarative Configuration Management

    Declarative Automated Deployment

    Machine Documentation

    Remarks on Automation in General

Enforced Guidelines

    Some Examples of Rules

    Evolving the Guidelines

    Enforcement or Encouragement

    Declarative Guidelines

    A Matter of Tools

    Guidelines or Design Documentation?

    Warranty Sticker Void if Tampered With

    Trust-First Culture

Constrained Behavior

    Making It Easy to Do the Right Thing

    Making Mistakes Impossible: Error-Proof API

Design Principles for Documentation Avoidance

    Replaceability First

    Consistency First

Example: The Zero Documentation Game

    Continuous Training

Summary

Chapter 11: Beyond Documentation: Living Design

Listening to the Documentation

    What Happened to the Language of the Domain?

    Programming by Coincidence Design

Deliberate Decision Making

     “Deliberate Decision” Does Not Mean “Upfront Decision”

    Documentation Is a Form of Code Review

Shameful Documentation

    Example: Shameful Documentation

    The Troubleshooting Guide

    Shameful Code Documentation

    Documenting Errors or Avoiding Errors?

Documentation-Driven Development

    Documentation to Keep You Honest

    The Apparent Contradiction Between Documentation Driven and “Avoiding Documentation”

Abusing Living Documentation (Anti-pattern)

Procrastination by Living Documentation

Biodegradable Documentation

Hygienic Transparency

    Diagnostic Tools

    Positive Pressure to Clean the Inside

Design Skills Everywhere

Reporter Porter Interviewing Mr. Living Doc Doc

Summary

Chapter 12: Living Architecture Documentation

Documenting the Problem

    An Example of a Problem Brief

Explicit Quality Attributes

    Stake-Driven Architecture Documentation

    Explicit Assumptions

    Brevity Suggests Quality

    Evolving Continuously: Change-Friendly Documentation

Decision Logs

    An Example of a Structured Decision Log

    Journals or Blogs as Brain Dumps

Fractal Architecture Documentation

The Architecture Landscape

    Architecture Diagrams and Notations

An Architecture Codex

Transparent Architecture

    Architectural Annotations

    Enforced Design Decisions

Architectural Reality Check

Test-Driven Architecture

    Quality Attributes as Scenarios

    Quality Attributes at Runtime in Production

    Other Quality Attributes

    From Fragmented Knowledge to Usable Documentation

Small-Scale Simulation as Living Architecture Documentation

    The Desirable Properties of a Small-Scale Simulation

    Techniques to Simplify a System

    Building a Small-Scale Simulation Is Half the Fun

System Metaphor

    Explaining a System by Talking About Another System

    Useful Even Without Prior Knowledge

    A Metaphor in Another Metaphor

Summary

Chapter 13: Introducing Living Documentation to a New Environment

Undercover Experiments

    Official Ambition

New Things Have to Work and Have to Be Accepted

    Starting Gently

    Going Big and Visible

Case Study: A Tale of Introducing Living Documentation to a Team Member

    Conversations First

    The First Debriefing

    Time to Talk About the Code

    Decision Logs and Guided Tours

Common Objections to Living Documentation

    Annotations Are Not Meant for Documentation

     “We Do It Already”

Migrating Legacy Documentation into Living Documentation

Marginal Documentation

Case Study: Introducing Living Documentation in a Batch System

    README and Ready-Made Documentation

    Business Behavior

    Visible Workings and a Single Source of Truth

    Integrated Documentation for Developers and a Living Glossary for Other Stakeholders

    A Living Diagram to Show the Design Intent

    Contact Information and Guided Tours

    Microservices Big Picture

Selling Living Documentation to Management

    Starting with an Actual Problem

    A Living Documentation Initiative

    Contrasting the Current Situation with the Promise of a Better World to Match People’s Aspirations

Compliance in Spirit

    Case Study: Compliance with ITIL

    The ITIL Example

Summary

Chapter 14: Documenting Legacy Applications

Documentation Bankruptcy

Legacy Application as Fossilized Knowledge

    Archeology

Bubble Context

Superimposed Structure

Highlighted Structure

External Annotations

Biodegradable Transformation

    Example: Strangler Application

    Example: Bankruptcy

Agree on Maxims

Enforced Legacy Rules

Summary

Chapter 15: Extra: Conspicuous Documentation

Focusing on Differences

    How Is Your Lemon?

Tell Only What’s Unknown

    Segmenting by Known Audience

    Flexible Content

    Low-Fidelity Content

    Visual Facilitation

Search-Friendly Documentation

Concrete Examples, Together, Now

    In Practice

    Fast Media and Prior Preparation

    Together, Now

Stack Overflow Documentation

Affordable and Attractive

    Specs Digest

    Easter Eggs and Fun Anecdotes

    Promoting News

Unorthodox Media

    Maxims

    Posters and Domestic Ads

    Meme-Based Posters

    Information Radiators

    Humor and Cheap Media

    Goodies/Swag

    Comics

    Infodecks

    Visualizations and Animations

    LEGO Bricks

    Furniture

    3D Printed Stuff

Summary

 



9780134689326    TOC    4/17/2019