Living Documentation: Continuous Knowledge Sharing by Design, First Edition

Living Documentation: Continuous Knowledge Sharing by Design, First Edition

by Cyrille Martraire
Released May 2019
Publisher(s): Addison-Wesley Professional
ISBN: 9780134689418

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

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

Table of contents

  1. Cover Page
  2. About This eBook
  3. Halftitle Page
  4. Title Page
  5. Copyright Page
  6. Dedication Page
  7. Contents
  8. Acknowledgments
  9. About the Author
  10. Introduction
  11. Figure Credits
  12. Chapter 1: Rethinking Documentation
    1. A Tale from the Land of Living Documentation
      1. Why This Feature?
      2. Tomorrow You Won’t Need This Sketch Anymore
      3. Sorry, We Don’t Have Marketing Documents!
      4. You Keep Using This Word, but This Is Not What It Means
      5. Show Me the Big Picture, and You’ll See What’s Wrong There
      6. The Future of Living Documentation Is Now
    2. The Problem with Traditional Documentation
      1. Documentation Is Not Cool, Usually
      2. The Flaws of Documentation
      3. The Agile Manifesto and Documentation
      4. It’s Time for Documentation 2.0
    3. Documentation Is About Knowledge
      1. The Origination of Knowledge
      2. How Does Knowledge Evolve?
      3. Why Knowledge Is Necessary
    4. Documentation Is About Transferring Knowledge
      1. Focusing on What Matters
    5. Core Principles of Living Documentation
      1. Reliable
      2. Low Effort
      3. Collaborative
      4. Insightful
      5. How Ants Exchange Knowledge: Stigmergy
    6. Most Knowledge Is Already There
    7. Internal Documentation
      1. Internal Versus External Documentation
      2. Examples of Internal and External Documentation
      3. Preferring Internal Documentation
      4. In Situ Documentation
      5. Machine-Readable Documentation
    8. Specific Versus Generic Knowledge
      1. Learning Generic Knowledge
      2. Focusing on Specific Knowledge
    9. Ensuring Documentation Accuracy
      1. Accuracy Mechanism for Reliable Documentation
      2. When Documentation Does Not Need an Accuracy Mechanism
    10. Big Questions to Challenge Your Documentation
      1. Questioning the Need for Documentation at All
      2. Need for Documentation Because of Lack of Trust
      3. Just-in-Time Documentation, or a Cheap Option on Future Knowledge
      4. Questioning the Need for Traditional Documentation
      5. Minimizing Extra Work Now
      6. Minimizing Extra Work Later
    11. Making an Activity Fun
    12. Documentation Reboot
      1. Living Documentation: The Very Short Version
      2. Approaches to Better Documentation
    13. A Gateway to DDD
      1. Domain-Driven Design in a Nutshell
      2. Living Documentation and Domain-Driven Design
      3. When Living Documentation Is an Application of DDD
      4. A Story of Mutual Roots Between BDD, DDD, XP, and Living Documentation
    14. Summary
  13. Chapter 2: Behavior-Driven Development as an Example of Living Specifications
    1. BDD Is All About Conversations
    2. BDD with Automation Is All About Living Documentation
      1. Redundancy and Reconciliation
    3. The Anatomy of Scenarios in a File
      1. The Intent of a Feature File
      2. Feature File Scenarios
      3. Specification Details
      4. Tags in Feature Files
      5. Scenarios as Interactive Living Documentation
      6. Scenarios in Boring Paper Documents
    4. A Feature File Example
    5. A Canonical Case of Living Documentation in Every Aspect
    6. Going Further: Getting the Best of Your Living Documentation
      1. Property-Based Testing and BDD
    7. Summary
  14. Chapter 3: Knowledge Exploitation
    1. Identifying Authoritative Knowledge
    2. Where Is the Knowledge Now?
    3. Single-Source Publishing
      1. Some Examples of Producing a Published Document
      2. A Published Snapshot with a Version Number
      3. Remarks
    4. Setting Up a Reconciliation Mechanism (aka Verification Mechanism)
      1. Running Consistency Tests
      2. Reconciliation on the Test Assumptions
      3. Published Contracts
    5. Consolidating Dispersed Facts
      1. How Consolidation Works
      2. Consolidation Implementation Considerations
    6. Ready-Made Documentation
      1. The Power of a Standard Vocabulary
      2. Linking to Standard Knowledge
      3. More Than Just Vocabulary
      4. Using Ready-Made Knowledge in Conversation to Speed Up Knowledge Transfer
    7. Tools History
    8. Summary
  15. Chapter 4: Knowledge Augmentation
    1. When Programming Languages Are Not Enough
    2. Documentation Using Annotations
      1. Annotations as More Than Tags
      2. Describing the Rationale Behind Decisions
      3. Embedded Learning
    3. Documentation by Convention
      1. Living Documentation in Legacy Code with Conventions
      2. Documenting the Conventions
      3. Consistently Adhering to Conventions
      4. The Limitations of Conventions
    4. External Documentation Methods
      1. Sidecar Files
      2. Metadata Databases
    5. Designing Custom Annotations
      1. Stereotypical Properties
      2. Stereotypes and Tactical Patterns
      3. Using Meaningful Annotation Package Names
      4. Hijacking Standard Annotations
      5. Standard Annotation: @Aspect and Aspect-Oriented Programming
      6. Annotation by Default or Unless Necessary
    6. Handling Module-Wide Knowledge
      1. Dealing with Many Kinds of Modules
      2. Module-Wide Augmentation In Practice
    7. Intrinsic Knowledge Augmentation
    8. Machine-Accessible Documentation
    9. Recording Your Rationale
      1. What’s in a Rationale?
      2. Making the Rationale Explicit
      3. Beyond Documentation: Motivated Design
      4. Avoid Documenting Speculation
      5. Skills as Pre-Documented Rationales
      6. Recording the Rationale as an Enabler for Change
    10. Acknowledging Your Influences (aka Project Bibliography)
      1. Declaring Your Style
    11. Commit Messages as Comprehensive Documentation
      1. Commit Guidelines
    12. Summary
  16. Chapter 5: Living Curation: Identifying Authoritative Knowledge
    1. Dynamic Curation
      1. Examples of Dynamic Curation
      2. Editorial Curation
      3. Low-Maintenance Dynamic Curation
      4. One Corpus of Knowledge for Multiple Uses
      5. Scenario Digests
    2. Highlighting the Core
    3. Highlighting Inspiring Exemplars
    4. Guided Tours and Sightseeing Maps
      1. Creating a Sightseeing Map
      2. Creating a Guided Tour
      3. Creating a Living Guided Tour
      4. A Poor Man’s Literate Programming
    5. Summing Up: The Curator Preparing an Art Exhibition
      1. Selecting and Organizing Existing Knowledge
      2. Adding What’s Missing When Needed
      3. Accessibility for People Who Can’t Attend and for Posterity
    6. Summary
  17. Chapter 6: Automating Documentation
    1. Living Documents
      1. Steps in Creating a Living Document
      2. Presentation Rules
    2. Living Glossaries
      1. How a Living Glossary Works
      2. An Example Please!
      3. Information Curation for Living Documents
      4. Creating a Glossary Within a Bounded Context
      5. Case Study of a Living Glossary
    3. Living Diagrams
      1. Diagrams Assist in Conversations
      2. One Diagram, One Story
      3. Living Diagrams to Keep You Honest
      4. The Quest for the Perfect Diagram
      5. Rendering a Living Diagram
      6. Visualization Guidelines
      7. Example: Hexagonal Architecture Living Diagram
      8. Case Study: A Business Overview as a Living Diagram
      9. Example: A Context Diagram
      10. The Challenges with Automated Generation of Design Documentation
    4. Summary
  18. Chapter 7: Runtime Documentation
    1. Example: Living Services Diagram
      1. A Matter of Augmented Code but at Runtime
      2. Discovering the Architecture
      3. The Magic That Makes This Work
      4. Going Further
      5. Visible Workings: Working Software as Its Own Documentation
    2. Visible Tests
      1. Domain-Specific Notation
      2. Generating Custom Domain-Specific Diagrams to Get Visual Feedback
    3. Example: A Visible Test When Using Event Sourcing
      1. A Concrete Example in Code
      2. Living Diagrams from Event Sourcing Scenarios
    4. Introspectable Workings: Code in Memory as a Source of Knowledge
      1. Introspecting with Reflection
      2. Introspecting Without Reflection
    5. Summary
  19. Chapter 8: Refactorable Documentation
    1. Code as Documentation
      1. Text Layout
      2. Coding Conventions
    2. Naming as the Primary Documentation
      1. Composed Methods: You Need to Name Them
      2. Idiomatic Naming Is Contextual
      3. Coding Against a Framework
    3. Type-Driven Documentation
      1. From Primitives to Types
      2. Documented Types and Integrated Documentation
      3. Types and Associations
      4. Types over Comments
    4. The Composed Method
    5. Fluent Style
      1. Using an Internal DSL
      2. Implementing a Fluent Interface
      3. Fluent Tests
      4. Creating a DSTL
      5. When Not to Use a Fluent Style
    6. Case Study: An Example of Refactoring Code, Guided by Comments
    7. Integrated Documentation
      1. Type Hierarchy
      2. Code Searching
      3. Semantics Derived from Actual Usage
    8. Using Plain-Text Diagrams
      1. Example: Plain-Text Diagrams
      2. Diagrams as Code
    9. Summary
  20. Chapter 9: Stable Documentation
    1. Evergreen Content
      1. Requirements Are More Stable Than Design Decisions
      2. High-Level Goals Tend to Be Stable
      3. A Lot of Knowledge Is Less Stable Than It Looks
      4. Case Study: A README File
    2. Tips for Evergreen Documentation
      1. Avoiding Mixing Strategy Documentation with the Documentation of Its Implementation
      2. Ensuring Stability
      3. Using Perennial Naming
      4. Organizing Artifacts Along Stable Axes
    3. Linked Knowledge
      1. Volatile-to-Stable Dependencies
      2. Broken Link Checkers
      3. Link Registry
      4. Bookmarked Searches
    4. Categories of Stable Knowledge
      1. Evergreen README
    5. Vision Statement
      1. Domain Vision Statements
      2. Goals
      3. Impact Mapping
    6. Investing in Stable Knowledge
      1. Domain Immersion
      2. Investigation Wall
      3. Domain Training
      4. Live-My-Life Sessions
      5. Shadow Users
      6. A Long-Term Investment
    7. Summary
  21. Chapter 10: Avoiding Traditional Documentation
    1. Conversations About Formal Documentation
      1. Wiio’s Laws
      2. The Rule of Three Interpretations
      3. Obstacles to Conversations
    2. Working Collectively for Continuous Knowledge Sharing
      1. Pair Programming
      2. Cross Programming
      3. Mob Programming
      4. The Three Amigos (or More)
      5. Event Storming as an Onboarding Process
      6. Knowledge Transfer Sessions
      7. Continuous Documentation
      8. Truck Factor
    3. Coffee Machine Communication
    4. Idea Sedimentation
    5. Throw-Away Documentation
    6. On-Demand Documentation
      1. Just-in-Time Documentation
      2. Provoking Just-in-Time Learning Early
      3. Astonishment Report
      4. Including Some Upfront Documentation
    7. Interactive Documentation
    8. Declarative Automation
      1. Declarative Style
      2. Declarative Dependency Management
      3. Declarative Configuration Management
      4. Declarative Automated Deployment
      5. Machine Documentation
      6. Remarks on Automation in General
    9. Enforced Guidelines
      1. Some Examples of Rules
      2. Evolving the Guidelines
      3. Enforcement or Encouragement
      4. Declarative Guidelines
      5. A Matter of Tools
      6. Guidelines or Design Documentation?
      7. Warranty Sticker Void if Tampered With
      8. Trust-First Culture
    10. Constrained Behavior
      1. Making It Easy to Do the Right Thing
      2. Making Mistakes Impossible: Error-Proof API
    11. Design Principles for Documentation Avoidance
      1. Replaceability First
      2. Consistency First
    12. Example: The Zero Documentation Game
      1. Continuous Training
    13. Summary
  22. Chapter 11: Beyond Documentation: Living Design
    1. Listening to the Documentation
      1. What Happened to the Language of the Domain?
      2. Programming by Coincidence Design
    2. Deliberate Decision Making
      1. “Deliberate Decision” Does Not Mean “Upfront Decision”
      2. Documentation Is a Form of Code Review
    3. Shameful Documentation
      1. Example: Shameful Documentation
      2. The Troubleshooting Guide
      3. Shameful Code Documentation
      4. Documenting Errors or Avoiding Errors?
    4. Documentation-Driven Development
      1. Documentation to Keep You Honest
      2. The Apparent Contradiction Between Documentation Driven and “Avoiding Documentation”
    5. Abusing Living Documentation (Anti-pattern)
    6. Procrastination by Living Documentation
    7. Biodegradable Documentation
    8. Hygienic Transparency
      1. Diagnostic Tools
      2. Positive Pressure to Clean the Inside
    9. Design Skills Everywhere
    10. Reporter Porter Interviewing Mr. Living Doc Doc
    11. Summary
  23. Chapter 12: Living Architecture Documentation
    1. Documenting the Problem
      1. An Example of a Problem Brief
    2. Explicit Quality Attributes
      1. Stake-Driven Architecture Documentation
      2. Explicit Assumptions
      3. Brevity Suggests Quality
      4. Evolving Continuously: Change-Friendly Documentation
    3. Decision Logs
      1. An Example of a Structured Decision Log
      2. Journals or Blogs as Brain Dumps
    4. Fractal Architecture Documentation
    5. The Architecture Landscape
      1. Architecture Diagrams and Notations
    6. An Architecture Codex
    7. Transparent Architecture
      1. Architectural Annotations
      2. Enforced Design Decisions
    8. Architectural Reality Check
    9. Test-Driven Architecture
      1. Quality Attributes as Scenarios
      2. Quality Attributes at Runtime in Production
      3. Other Quality Attributes
      4. From Fragmented Knowledge to Usable Documentation
    10. Small-Scale Simulation as Living Architecture Documentation
      1. The Desirable Properties of a Small-Scale Simulation
      2. Techniques to Simplify a System
      3. Building a Small-Scale Simulation Is Half the Fun
    11. System Metaphor
      1. Explaining a System by Talking About Another System
      2. Useful Even Without Prior Knowledge
      3. A Metaphor in Another Metaphor
    12. Summary
  24. Chapter 13: Introducing Living Documentation to a New Environment
    1. Undercover Experiments
      1. Official Ambition
    2. New Things Have to Work and Have to Be Accepted
      1. Starting Gently
      2. Going Big and Visible
    3. Case Study: A Tale of Introducing Living Documentation to a Team Member
      1. Conversations First
      2. The First Debriefing
      3. Time to Talk About the Code
      4. Decision Logs and Guided Tours
    4. Common Objections to Living Documentation
      1. Annotations Are Not Meant for Documentation
      2. “We Do It Already”
    5. Migrating Legacy Documentation into Living Documentation
    6. Marginal Documentation
    7. Case Study: Introducing Living Documentation in a Batch System
      1. README and Ready-Made Documentation
      2. Business Behavior
      3. Visible Workings and a Single Source of Truth
      4. Integrated Documentation for Developers and a Living Glossary for Other Stakeholders
      5. A Living Diagram to Show the Design Intent
      6. Contact Information and Guided Tours
      7. Microservices Big Picture
    8. Selling Living Documentation to Management
      1. Starting with an Actual Problem
      2. A Living Documentation Initiative
      3. Contrasting the Current Situation with the Promise of a Better World to Match People’s Aspirations
    9. Compliance in Spirit
      1. Case Study: Compliance with ITIL
      2. The ITIL Example
    10. Summary
  25. Chapter 14: Documenting Legacy Applications
    1. Documentation Bankruptcy
    2. Legacy Application as Fossilized Knowledge
      1. Archeology
    3. Bubble Context
    4. Superimposed Structure
    5. Highlighted Structure
    6. External Annotations
    7. Biodegradable Transformation
      1. Example: Strangler Application
      2. Example: Bankruptcy
    8. Agree on Maxims
    9. Enforced Legacy Rules
    10. Summary
  26. Chapter 15: Extra: Conspicuous Documentation
    1. Focusing on Differences
      1. How Is Your Lemon?
    2. Tell Only What’s Unknown
      1. Segmenting by Known Audience
      2. Flexible Content
      3. Low-Fidelity Content
      4. Visual Facilitation
    3. Search-Friendly Documentation
    4. Concrete Examples, Together, Now
      1. In Practice
      2. Fast Media and Prior Preparation
      3. Together, Now
    5. Stack Overflow Documentation
    6. Affordable and Attractive
      1. Specs Digest
      2. Easter Eggs and Fun Anecdotes
      3. Promoting News
    7. Unorthodox Media
      1. Maxims
      2. Posters and Domestic Ads
      3. Meme-Based Posters
      4. Information Radiators
      5. Humor and Cheap Media
      6. Goodies/Swag
      7. Comics
      8. Infodecks
      9. Visualizations and Animations
      10. LEGO Bricks
      11. Furniture
      12. 3D Printed Stuff
    8. Summary
  27. Index
  28. Code Snippets

Product information

  • Title: Living Documentation: Continuous Knowledge Sharing by Design, First Edition
  • Author(s): Cyrille Martraire
  • Release date: May 2019
  • Publisher(s): Addison-Wesley Professional
  • ISBN: 9780134689418