Willkommen, schön sind Sie da!
Logo Ex Libris

Living Documentation

  • E-Book (pdf)
(0) Erste Bewertung abgeben
Alle Bewertungen ansehen
Use an Approach Inspired by Domain-Driven Design to Build Documentation That Evolves to Maximize Value Throughout Your Developme... Weiterlesen
E-Books ganz einfach mit der kostenlosen Ex Libris-Reader-App lesen. Hier erhalten Sie Ihren Download-Link.
CHF 33.90
Download steht sofort bereit
Informationen zu E-Books
E-Books eignen sich auch für mobile Geräte (sehen Sie dazu die Anleitungen).
E-Books von Ex Libris sind mit Adobe DRM kopiergeschützt: Erfahren Sie mehr.
Weitere Informationen finden Sie hier.


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


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.



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


Low Effort



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


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


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


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


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


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


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


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


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


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


Impact Mapping

Investing in Stable Knowledge

Domain Immersion

Investigation Wall

Domain Training

Live-My-Life Sessions

Shadow Users

A Long-Term Investment


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


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


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


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


Chapter 14: Documenting Legacy Applications

Documentation Bankruptcy

Legacy Application as Fossilized Knowledge


Bubble Context

Superimposed Structure

Highlighted Structure

External Annotations

Biodegradable Transformation

Example: Strangler Application

Example: Bankruptcy

Agree on Maxims

Enforced Legacy Rules


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


Posters and Domestic Ads

Meme-Based Posters

Information Radiators

Humor and Cheap Media




Visualizations and Animations

LEGO Bricks


3D Printed Stuff


9780134689326 TOC 4/17/2019


Titel: Living Documentation
Untertitel: Continuous Knowledge Sharing by Design
EAN: 9780134689425
Digitaler Kopierschutz: frei
Format: E-Book (pdf)
Hersteller: Pearson ITP
Genre: Programmiersprachen
Veröffentlichung: 25.05.2019
Dateigrösse: 13.2 MB