Living Documentation

Use an Approach Inspired by Domain-Driven Design to Build Documentation That Evolves to Maximize Value Throughout Your Development Lifecycle

Software documentation can come to life, stay dynamic, and actually help you build better software. Writing for developers, coding architects, and other software professionals, Living Documentation shows how to create documentation that evolves throughout your entire design and development lifecycle.

Through patterns, clarifying illustrations, and concrete examples, Cyrille Martraire demonstrates how to use well-crafted artifacts and automation to dramatically improve the value of documentation at minimal extra cost. Whatever your domain, language, or technologies, you don't have to choose between working software and comprehensive, high-quality documentation: you can have both.

· Extract and augment available knowledge, and make it useful through living curation

· Automate the creation of documentation and diagrams that evolve as knowledge changes

· Use development tools to refactor documentation

· Leverage documentation to improve software designs

· Introduce living documentation to new and legacy environments

Autorentext

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.

Inhalt

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

…