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
…