Cyrille Martraire

Living Documentation

Continuous Knowledge Sharing by Design

• Gebundenes Buch

Produktbeschreibung

This concise guide introduces and thoroughly illuminates the concept of living documentation that changes at the same pace as software design and development, from establishment of business goals to capturing domain knowledge, creating architecture, designing software, coding, and deployment. Replete with clarifying illustrations and concrete examples, it shows how to dramatically improve your documentation at minimal extra cost by using well-crafted artifacts and judicious automation.

Produktdetails

• Verlag: Addison-Wesley
• Seitenzahl: 480
• Erscheinungstermin: 4. Juni 2019
• Englisch
• Abmessung: 241mm x 182mm x 30mm
• Gewicht: 921g
• ISBN-13: 9780134689326
• ISBN-10: 0134689321
• Artikelnr.: 48094687

Autorenporträt

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.

Inhaltsangabe

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