Living Documentation by design, with Domain-Driven Design
Living Documentation by design, with Domain-Driven Design
Accelerate Delivery Through Continuous Investment on Knowledge
About the Book
The book is now published by Addison-Wesley Professional in print and ebook, and is available online everywhere.
You don't necessarily have to chose between Working Software and Extensive Documentation!
The approach "Specification by Example" has introduced the idea of a "Living Documentation". In this approach, examples of behavior are used for documentation and are also promoted into automated tests. Whenever a test fails, it signals the documentation is no longer in sync with the code so it can just be fixed quickly.
This has shown that it is possible to have useful documentation that doesn't suffer the fate of getting obsolete once written.
But we can go much further. This book expands on this idea of a Living Documentation. It shows how a living documentation evolves at the same pace than the code, for all aspects of a project, from the business goals to the business domain knowledge, architecture and design, processes and deployment.
This book explains the theory and describes a number of techniques, with illustrations and concrete examples. You will learn how to start investing into documentation that is always up to date, at a minimal extra cost thanks to well-crafted artifacts and the use of automation.
- Note to reviewers
A simple question
- Are you happy with the documentation you create?
- About this book
- How to read this book?
Part 1 Reconsidering 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
- The flaws of documentation
- The agile manifesto and documentation
- It’s time for Documentation 2.0
- It’s all about knowledge
- How does that knowledge evolve?
The reasons why knowledge is necessary
- And now for a pedantic word: Stigmergy
- Software Programming as Theory Building and Passing
Documentation is about transferring knowledge
- Choosing the right media
Specific vs. Generic Knowledge
- Generic Knowledge
- Learn generic knowledge
- Focus on Specific Knowledge
- Knowledge is already there
- Internal vs. External documentation
- Choosing between external or internal documentation
- In situ Documentation
- Machine-readable documentation
- Documentation by Design
- Accuracy Mechanism for a reliable documentation for fast-changing projects
The Documentation Checklist
- Questioning the need for documentation at all
- Need for documentation because lack of trust
- Just-In-Time Documentation, or Cheap Option on Future Knowledge
- Questioning the need for traditional documentation
- Minimizing the extra work now
- Minimizing the extra work later
- Living Documentation - The Very Short Version
- Approaches to better documentation
- No Documentation
- Stable Documentation
- Refactor-Friendly Documentation
- Automated Documentation
- Runtime Documentation
- Beyond Documentation
Core Principles of Living Documentation
A Gateway Drug to DDD
- Domain-Driven Design in a nutshell
- Living Documentation and Domain-Driven Design
- When Living Documentation is an application of DDD
A principled approach
- A tale from the land of Living Documentation
Part 2 Living Documentation exemplified by Behavior-Driven Development
A key example of Living Documentation: BDD
- BDD is all about conversations
- BDD with automation is all about Living Documentation
- Redundancy + Reconciliation
- Anatomy of the scenarios in file
- Interactive Living Documentation
- Feature File: another Example
- How does it work?
- A canonical case of Living Documentation in every aspect
- Going further: Getting the best of your living documentation
- Scenario: Present Value of a single cash amount
- No guarantee of correctness
- Property-Based Testing and BDD
- Manual glossary
- Linking to non-functional knowledge
- A key example of Living Documentation: BDD
Part 3 Knowledge Exploitation & Augmentation
- Identify authoritative knowledge
- Where is this knowledge now?
Single Sourcing with a Publishing Mechanism (aka Single Source Publishing)
- Some examples of producing a published document
- Published Snapshot with a version number
Reconciliation Mechanism (aka Verification Mechanism)
- Consistency Tests
- Reconciliation on the test assumptions
- Published Contracts
- How it works
- Implementation remarks
- The power of a standard vocabulary
- Link to standard knowledge
- Searching for the reference
- More than just vocabulary
- Ready-made knowledge in conversation to speed up knowledge transfer
- Tools History
- When programming languages are not enough
Documentation by Annotations
- Annotations are more than tags
- A good place to describe the rationale behind the decisions
- Annotations for learning on the job
Documentation by Convention
- Legacy with conventions has opportunities for Living Documentation
- Document the Conventions
- Conventions have limitations
- Sidecar files
- Metadata Database
Designing Custom Annotations
- Stereotypical Properties
- Stereotypes and tactical patterns
- Meaningful annotations package names
- Hijacking standard annotations
- Standard Annotation @Aspect and Aspect-Oriented Programming
- Annotation by default or unless necessary
- Many kinds of modules
- In practice
- Intrinsic Knowledge Augmentation
- Inspiring Exemplars
- Machine Accessible Documentation
- Other similar approaches
Record Your Rationale
- What’s in a rationale?
- Make it explicit
- Beyond Documentation: Motivated Design
- Don’t document speculation
- Skills as pre-documented rationales
- Recording the rationale as an enabler for change
Commit Messages as Comprehensive Documentation
- Commit Guidelines
- Scope of the change
- Machine-Accessible information
- Editorial curation
- Low-maintenance dynamic curation
- One corpus of knowledge for multiple uses
- Scenario Digest
- Highlighted Core (Eric Evans)
Guided Tour, Sightseeing Map
- A sightseeing map
- An example in Java
- A Guided Tour Example
- Living Guided Tour
- The implementation
- Knowledge Exploitation
Part 4 Automated Documentation
- Anatomy of a living document.
- Presentation Rules
- How it works
- An example please!
- Practical Implementation
- Information Curation
- Glossary by Bounded Context
- Case Study
- Diagrams help conversations
- Editorial Perspective
- Living Diagram to keep you honest
- The quest for the perfect diagram
- Visualization guidelines:
Hexagonal Architecture Living Diagram
- The idea
- The architecture is already documented
- The architecture is already in the code
- Creating the living diagram
- Possible Evolutions
Case Study: Business Overview as a Living Diagram
- The idea
- Practical Implementation
- How does this Living Diagram fit with the patterns of Living Documentation?
Living Services Diagram
- A matter of Augmented Code, but at runtime
- Discover the architecture
- The magic to make this work
- Going further
- Hyperlinks to the corresponding source code location
- Augmented Code & Knowledge Consolidation
- Limitations & Benefits
Domain-Specific Diagrams (aka Visible Tests)
- Domain-Specific Notations
- Generating custom domain-specific diagrams to get visual feedback
- A complement to Gherkin scenarios?
- Pattern-Oriented Living Diagram
- Living Document
Part 5 Runtime Documentation
Visible Workings: Working Software as its own Documentation
- Working software as documentation
- Visible Workings
- Introspecting by reflection
- Introspecting without reflection
- Visible Workings: Working Software as its own Documentation
Part 6 Refactoring-Friendly Documentation
- Plain-Text Artifacts
- Source Control is the Reference
- An example
- Diagram as Code
Code is Documentation
- Text Layout
- Coding Conventions
- Type Hierarchy
- Code search
- Semantics derived from the actual usage
Naming As The Primary Documentation
- Naming: browsing a thesaurus
- Composed methods, you need to name them.
- Types and Associations
- Types over Comments
- Composed Method (Kent Beck)
- An Internal DSL
- Implementing a Fluent Interface
- Fluent Tests
- Test DSL aka DSTL
- Fluent All the Things! Not.
- Case Study: An example of refactoring the code, guided by comments
Living Documentation with Event Sourcing tests
- A concrete example in code
- How does it work?
- Living Diagrams from Event Sourcing scenarios
Part 7 Stable Documentation
- Design Vs Requirements
- A lot of knowledge is less stable than it looks.
- Case Study: a README file
- Evergreen README
- In closing
- Don’t Mix Strategy Documentation with the documentation of its implementation
- Domain Vision Statement
- Impact Mapping
- Traceability to the goals
- Stable Knowledge can also be code
- Organizing artifacts along stable axes
- Linkable Knowledge
- Volatile To Stable
- Link Registry
- Bookmarked Search
- Contract Test as a Reconciliation Mechanism
Acknowledge your influences
- Project Bibliography
- Declare your Style
- Investigation Wall
- Domain Training
- Live-my-Life Sessions
- Shadow User
- A long-term investment
- Evergreen Document
Part 8 No Documentation
Conversations Over Formal Documentation
- Wiio’s laws
- The Rule of Three Interpretations
- Obstacles to conversations
- Knowledge Transfer sessions
- Interactive Documentation
- Event Storming as an on-boarding process
- Continuous Documentation
- Truck Factor
Coffee Machine Communication
- Ideas Sedimentation
- Throw-Away Documentation
- Just-In-Time Documentation
- Provoking Just-In-Time Learning Early
- Astonishment Report
- Some Upfront Documentation?
- Declarative Dependency Management
- Declarative Configuration Management
- Declarative Automated Deployment
- Machines Documentation
- Remarks on automation in general
- 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
- An example
- The Troubleshooting Guide
- Don’t tolerate the documented pain
- Shameful code documentation
Don’t document, influence or constraint behavior instead!
- Make It Easy to Do the Right Thing
- Making Mistakes Impossible - Error-Proof API
Design principles for documentation avoidance
Zero documentation & Gamification
- Continuous Training
- Conversations Over Formal Documentation
Part 9 Beyond Documentation
- Documentation to keep you honest
- The apparent contradiction between Documentation-Driven and “NoDocumentation”
Abusing Living Documentation
- Living Documentation with Moderation
- Procrastinate on Living Documentation
Listen To The Documentation
- What happened to the Language of the Domain?
- Programming by coincidence Design
- Deliberate Decisions
- Deliberate decision does not mean upfront decision
- Documentation is a form of code review
- Biodegradable Documentation
- Diagnosis tools
- A Positive Pressure to clean the inside.
- Living Documentation Going Wild
- BREAKING!!! Live Interview: Mrs Reporter Porter interviewing Mr Living Doc Doctor!
- Documentation-Driven Development
Part 10 Living Design & Architecture Documentation
Living Design & Architecture
- The design skills pre-requisite
- Documenting errors, or avoiding errors?
- Naming (again)
- Design Annotations
- Enforced Design Decisions
- Coding against a framework
- Exemplarity in the case of design
System Metaphor (XP, DDD)
- Explaining a system by talking about another system
- With or without prior knowledge
- Architecture and documentation
- Everybody should know about the problem
- Quality Attributes
- Stake-Driven Architecture Documentation
- Explicit Assumptions
- Architecture Steering
- Decision Log
- Journal or Blog as a Brain Dump
- Fractal Polyglot Architecture
- Documentation Landscape
- Architecture Diagrams & Notations
- Architecture Codex
- Transparent Architecture
- Test-Driven Architecture
- The desirable properties of a small-scale simulation
- Techniques to simplify the system
- Building the small-scale simulation is half the fun
- Living Design & Architecture
Part 11 Efficient Documentation
- Focus on Differences
- Only tell what’s unknown
- Search-Friendly Documentation
Concrete Examples, Together, Now
- In practice
- Fast Media and prior preparation
- Together, Now
- StackOverflow Documentation
Affordable & Attractive
- Specs Digest
- Easter Eggs & Fun Anecdotes
- Promoting News
- Posters & Domestic Ads
- Meme-based posters
- Information Radiators
- Very Short Story, Humor, Cheap media, and implicit message
- Digital Native!
- Visualizations & Animations
- Lego blocks
- 3D printed stuff
- Efficient Documentation
Part 12 Introducing Living Documentation
Introducing Living Documentation
- Undercover Experiments
- Official Ambition
- New Things Are difficult for two reasons: they have to work, and they have to be accepted.
- Starting gentle
- Going big and visible
- A Tale of introducing Living Documentation to a team member
- Common objections
- Migrating legacy documentation into a Living Documentation
- Marginal documentation
Introducing Living Documentation by example
- README and Ready-Made Documentation
- Business Behavior
- Visible Workings and Single Source of Truth
- Integrated Documentation for developers, Living Glossary for other stakeholders
- Living Diagram to show the design intent
- Contact information, and Guided Tour
- Micro-services Big Picture
Selling Living Documentation to management
- Start with an actual problem
- A Living Documentation initiative
- Contrasting current situation to the promise of a better world
- A Strategy must match people aspirations
Documentation for Compliance requirements
- The ITIL example
Documenting Legacy Applications
- Documentation Bankruptcy
- Legacy application as a complementary documentation
- Bubble Context (Evans)
- Superimposed Structure
- Highlighted Structure
- External Annotations
- Biodegradable Transformation
- Enforced Legacy Rules
Summing it up: the curator preparing an art exhibition
- Selecting and organizing existing knowledge
- Selecting and organizing existing knowledge
- Adding what’s missing when needed
- Accessible for people who can’t attend, and for posterity
- Introducing Living Documentation
The Leanpub 45-day 100% Happiness Guarantee
Within 45 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.
See full terms
Free Updates. DRM Free.
If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).
Most Leanpub books are available in PDF (for computers), EPUB (for phones and tablets) and MOBI (for Kindle). The formats that a book includes are shown at the top right corner of this page.
Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.
Ansible for KubernetesJeff Geerling
Ansible is a powerful infrastructure automation tool. Kubernetes is a powerful application deployment platform. Learn how to use these tools to automate massively-scalable, highly-available infrastructure.
Practical FP in Scala: A hands-on approachGabriel Volpe
A practical book aimed for those familiar with functional programming in Scala who are yet not confident about architecting an application from scratch.
Together, we will develop a purely functional application using the best libraries in the Cats ecosystem, while learning about design patterns and best practices.
Functional Design and ArchitectureAlexander Granin
Software Design in Functional Programming, Design Patterns and Practices, Methodologies and Application Architectures. How to build real software in Haskell with less efforts and low risks. The first complete source of knowledge.
Production HaskellMatt Parsons
Are you excited about Haskell, but don't know where to begin? Are you thrilled by the technical advantages, but worried about the unknown pitfalls? This book has you covered.
Tame your Work FlowSteve Tendon and Daniel Doiron
Do you need a high performance enterprise governance approach improving management, execution and delivery while dealing with multiple projects/products, events, stakeholders and teams? Giving you better bottom line results, faster time to market, less work, better predictability, happier employees, and delighted clients? Then learn about TameFlow!
Ansible for DevOpsJeff Geerling
Ansible is a simple, but powerful, server and configuration management tool. Learn to use Ansible effectively, whether you manage one server—or thousands.
Machine Learning EngineeringAndriy Burkov
"If you intend to use machine learning to solve business problems at scale, I'm delighted you got your hands on this book."
—Cassie Kozyrkov, Chief Decision Scientist at Google
"Foundational work about the reality of building machine learning models in production."
—Karolis Urbonas, Head of Machine Learning and Science at Amazon
C++ Best PracticesJason Turner
Level up your C++, get the tools working for you, eliminate common problems, and move on to more exciting things!
Composing SoftwareEric Elliott
All software design is composition: the act of breaking complex problems down into smaller problems and composing those solutions. Most developers have a limited understanding of compositional techniques. It's time for that to change.
El Manual del ManagerKeyvan Akbary, Félix López, and Álvaro Salazar
¿Has deseado alguna vez el haber tenido una buena introducción al rol del Engineering Manager? En este libro aprenderás lo necesario para ejercer el rol de una manera efectiva: Expectativas y Responsabilidades del Rol, 1-1s, Ayudar a Crecer, Objetivos, Planes de Carrera, Cultura, Feedback, Contratación, Cultura de Producto y mucho más.
The Tester's Library
8 BooksThe Tester's Library consists of eight five-star books that every software tester should read and re-read. As bound books, this collection would cost over $200. Even as e-books, their price would exceed $80, but in this bundle, their cost is only $49.99. Here are the books, and why they should be in your library: Perfect Software and Other...
11 BooksIn this bundle, you will find 10 different agile books. They are about different aspects of being agile. - finding a job - doing coding dojo's - Retrospectives - Personal kanban - a non-typical coaching book and even a book that gives you an insight in the lives of some agile people.
WTFlop 6M + HU - Beta Bundle
Marionette.js A to Z
Build A Better Backbone App
3 BooksThe best way to learn new development skills is through experience, but that takes time you don't have.Get the best of both worlds with this bundle: you'll learn how to produce modern web applications by learning from experienced developers like Derick Bailey and David Sulc. BackboneJS is one of the favorite tools on the web today, but it...
General Systems Thinker Bundle
5 BooksThe General Systems Thinker Bundle is just that: a bundle of five books to advance the reader one giant step toward improved thinking, based on General Systems principles. Four of the books are the complete General Systems Series. The fifth is fictional piece which shows some general systems thinkers in action. It's a mystery in which a group of...
Experiential Learning Bundle
4 BooksThis bundle provides all four volumes of the popular Experiential Learning Series at a savings of $20 over the price if purchased separately.
2 BooksAfter getting up and running with Ansible in Jeff Geerling's Ansible for DevOps, strengthen your skills managing tens to thousands of instances and services in Amazon's AWS cloud with Yan Kurniawan's Ansible for AWS.
Learn ECMAScript 6 inside and out
2 BooksFor any technology, it helps to get multiple points of view on the functionality to get the best possible understanding. For ECMAScript 6/2015, no two resources are recommended more frequently thanExploring ES6by Dr. Axel Rauschmayer andUnderstanding ECMAScript 6by Nicholas C. Zakas. These two points of view, investigating the specification and...
Software architecture, for systems old and new
2 BooksThis bundle includes books about hands-on software architecture.