Living documentation : continuous knowledge sharing by design

**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 Cover Half Title Title Page Copyright Page Dedication Contents Acknowledgments About the Author 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 Index A B C D E F G H I J K L M N O P Q R S T U V W X-Y-Z Software documentation: a necessary evil? It needn’t be! Documentation can come to life, evolve, stay dynamic, and actually help you build better software. 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. Language- and technology-agnostic. Living Documentation borrows powerful ideas from domain-driven design, helping you customize its concepts and apply its lessons to meet your changing documentation needs in your own specific domain. Cyrille Martraire proves that you don’t have to choose between working software and comprehensive, high-quality documentation: you can have the benefits of both. 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. -- Provided by publisher