Living Documentation by design, with Domain-Driven Design

Retired

This book is no longer available for sale.

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.

About the Author

Cyrille Martraire
Cyrille Martraire

Cyrille Martraire is a passionate developer since 1999. He's the co-founder and CTO of Arolla, a company specializing in software development and nothing else. With a love-and-hate relationship with documentation, he has experimented over more than 10 years with multiple ways to get smarter documentation, from automation to self-discipline.

Addicted to development at all scales, Cyrille still dedicates a large part of his energy for clients, hands-on in the code, yet also deeply involved in enterprise architecture or business analysis in finance. Passionate about design in every aspect (TDD, BDD, DDD), he also founded the Paris Software Craftsmanship community. Cyrille is a regular speaker in conferences in Europe and in other continents as well.

Table of Contents

  •  
    • Note to reviewers
    • A simple question
      • Are you happy with the documentation you create?
    • Preface
    • About this book
    • Acknowledgements
    • 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
    • Knowledge origination
      • 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 Documentation
      • Internal vs. External documentation
      • Examples
      • Choosing between external or internal documentation
      • In situ Documentation
      • Machine-readable documentation
    • Accuracy Mechanism
      • 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
    • Documentation Reboot
      • Approaches to better documentation
      • No Documentation
      • Stable Documentation
      • Refactor-Friendly Documentation
      • Automated Documentation
      • Runtime Documentation
      • Beyond Documentation
    • Core Principles of Living Documentation
      • Reliable
      • Low-Effort
      • Collaborative
      • Insightful
    • 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
      • Need
      • Values
      • Principles
      • Practices
      • Tools
    • Fun
  • 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
    • Description
      • Example
      • Scenario: Present Value of a single cash amount
      • No guarantee of correctness
      • Property-Based Testing and BDD
      • Manual glossary
      • Linking to non-functional knowledge
  • Part 3 Knowledge Exploitation & Augmentation
    • Knowledge Exploitation
      • 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
      • Remarks
    • Reconciliation Mechanism (aka Verification Mechanism)
      • Consistency Tests
      • Reconciliation on the test assumptions
      • Published Contracts
    • Information Consolidation
      • How it works
      • Implementation remarks
    • Ready-Made Documentation
      • 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
    • Augmented Code
      • 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
      • Discipline-Driven
      • 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
    • Module-Wide Knowledge
      • Many kinds of modules
      • In practice
    • Intrinsic Knowledge Augmentation
    • Inspiring Exemplars
    • Machine Accessible Documentation
    • Literate programming
      • 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
    • Dynamic Curation
      • Examples
      • 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
      • Related
  • Part 4 Automated Documentation
    • Living Document
      • Anatomy of a living document.
      • Presentation Rules
    • Living Glossary
      • How it works
      • An example please!
      • Practical Implementation
      • Information Curation
      • Glossary by Bounded Context
      • Case Study
    • Living Diagram
      • Diagrams help conversations
      • Editorial Perspective
      • Living Diagram to keep you honest
      • The quest for the perfect diagram
      • Rendering
      • 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
    • Context Diagram
      • 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
  • Part 5 Runtime Documentation
    • Visible Workings: Working Software as its own Documentation
      • Working software as documentation
      • Visible Workings
    • Introspectable Workings
      • Introspecting by reflection
      • Introspecting without reflection
  • Part 6 Refactoring-Friendly Documentation
    • Plain-Text Artifacts
    • Source Control is the Reference
    • Plain-Text Diagram
      • An example
      • Diagram as Code
    • Code is Documentation
      • Text Layout
      • Coding Conventions
    • Integrated Documentation
      • 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.
    • Type-Driven Documentation
      • Types and Associations
      • Types over Comments
    • Composed Method (Kent Beck)
    • Fluent Style
      • 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
    • Evergreen Document
      • Design Vs Requirements
      • Examples
      • 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
    • Vision Statement
      • Domain Vision Statement
      • Goals
      • Impact Mapping
      • Traceability to the goals
      • Stable Knowledge can also be code
    • Perennial Naming
      • Organizing artifacts along stable axes
      • Stability-Oriented
    • Knowledge Network
      • Linkable Knowledge
      • Volatile To Stable
      • Link Registry
      • Bookmarked Search
      • Contract Test as a Reconciliation Mechanism
    • Acknowledge your influences
      • Project Bibliography
      • Declare your Style
    • Domain Immersion
      • Investigation Wall
      • Domain Training
      • Live-my-Life Sessions
      • Shadow User
      • A long-term investment
  • Part 8 No Documentation
    • Conversations Over Formal Documentation
      • Wiio’s laws
      • The Rule of Three Interpretations
      • Obstacles to conversations
      • Knowledge Transfer sessions
      • Interactive Documentation
    • Working Collectively
      • Pair-Programming
      • Cross-Programming
      • Mob-programming
      • Event Storming as an on-boarding process
      • Continuous Documentation
      • Truck Factor
    • Coffee Machine Communication
      • Ideas Sedimentation
      • Throw-Away Documentation
    • On-Demand Documentation
      • Just-In-Time Documentation
      • Provoking Just-In-Time Learning Early
      • Astonishment Report
      • Some Upfront Documentation?
    • Declarative Automation
      • Declarative Dependency Management
      • Declarative Configuration Management
      • Declarative Automated Deployment
      • Machines 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
      • Trust-First
    • Shameful Documentation
      • 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
      • Replaceability-First
      • Consistency-First
    • Zero documentation & Gamification
      • Continuous Training
  • Part 9 Beyond Documentation
    • Documentation-Driven Development
      • 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
    • Hygienic Transparency
      • Diagnosis tools
      • A Positive Pressure to clean the inside.
    • Living Documentation Going Wild
    • BREAKING!!! Live Interview: Mrs Reporter Porter interviewing Mr Living Doc Doctor!
  • 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 Landscape
      • 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
    • Small-Scale Simulation
      • The desirable properties of a small-scale simulation
      • Techniques to simplify the system
      • Building the small-scale simulation is half the fun
  • Part 11 Efficient Documentation
    • 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
    • Unorthodox Media
      • Maxims
      • Posters & Domestic Ads
      • Meme-based posters
      • Information Radiators
      • Very Short Story, Humor, Cheap media, and implicit message
      • Digital Native!
      • Goodies
      • Comics
      • Infodecks
      • Visualizations & Animations
      • Lego blocks
      • Furniture
      • 3D printed stuff
  • 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
      • Archeology
      • Bubble Context (Evans)
      • Superimposed Structure
      • Highlighted Structure
      • External Annotations
      • Biodegradable Transformation
      • Maxims
      • 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
    • Closing

The Leanpub 60 Day 100% Happiness Guarantee

Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

Now, this is technically risky for us, since you'll have the book or course files either way. But we're so confident in our products and services, and in our authors and readers, that we're happy to offer a full money back guarantee for everything we sell.

You can only find out how good something is by trying it, and because of our 100% money back guarantee there's literally no risk to do so!

So, there's no reason not to click the Add to Cart button, is there?

See full terms...

80% Royalties. Earn $16 on a $20 book.

We pay 80% royalties. That's not a typo: you earn $16 on a $20 sale. If we sell 5000 non-refunded copies of your book or course for $20, you'll earn $80,000.

(Yes, some authors have already earned much more than that on Leanpub.)

In fact, authors have earnedover $13 millionwriting, publishing and selling on Leanpub.

Learn more about writing on Leanpub

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) and EPUB (for phones, tablets and 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.

Learn more about Leanpub's ebook formats and where to read them

Write and Publish on Leanpub

You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

Learn more about writing on Leanpub