Living Documentation

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.

Table of Contents

Chapter 1: Rethinking Documentation

Chapter 2: Behavior-Driven Development as an Example of Living Specifications

Chapter 3: Knowledge Exploitation

Chapter 4: Knowledge Augmentation

Chapter 5: Living Curation: Identifying Authoritative Knowledge

Chapter 6: Automating Documentation

Chapter 7: Runtime Documentation

Chapter 8: Refactorable Documentation

Chapter 9: Stable Documentation

Chapter 10: Avoiding Traditional Documentation

Chapter 11: Beyond Documentation: Living Design

Chapter 12: Living Architecture Documentation

Chapter 13: Introducing Living Documentation to a New Environment

Chapter 14: Documenting Legacy Applications

Chapter 15: Extra: Conspicuous Documentation

About the Author

Cyrille Martraire, CTO, co-founder, and partner at Arolla, has designed software since 1999. Martraire has participated in and led many large projects, mostly in capital finance. He founded the Paris Software Crafters community, speaks regularly at international conferences, and is passionate about all aspects of software design. He lives in Paris with his family.