Published by Addison-Wesley Professional (May 25, 2019) © 2019
Cyrille MartraireUse 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
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