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.
C++20 is the next big C++ standard after C++11. As C++11 did it, C++20 changes the way we program modern C++. This change is, in particular, due to the big four of C++20: ranges, coroutines, concepts, and modules.
The book is almost daily updated. These incremental updates ease my interaction with the proofreaders.
C++ Best PracticesJason Turner
Level up your C++, get the tools working for you, eliminate common problems, and move on to more exciting things!
Atomic KotlinBruce Eckel and Svetlana Isakova
For both beginning and experienced programmers! From the author of the multi-award-winning Thinking in C++ and Thinking in Java together with a member of the Kotlin language team comes a book that breaks the concepts into small, easy-to-digest "atoms," along with exercises supported by hints and solutions directly inside IntelliJ IDEA!
Sockets and PipesType Classes
Sockets and Pipes is not an introduction to Haskell; it is an introduction to writing software in Haskell. Using a handful of everyday Haskell libraries, this book walks through reading the HTTP specification and implementing it to create a web server.
Introducing EventStormingAlberto Brandolini
The deepest tutorial and explanation about EventStorming, straight from the inventor.
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.
Cloud StrategyGregor Hohpe
“Strategy is the difference between making a wish and making it come true.” A successful migration to the cloud can transform your organization, but it shouldn’t be driven by wishes. This book tells you how to develop a sound strategy guided by frameworks and decision models without being overly abstract nor getting lost in product details.
node-opcua by exampleEtienne Rossignon
Get the best out of node-opcua through a set of documented examples by the author himself that will allow you to create stunning OPCUA Servers or Clients.
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.
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.
Software Architecture for Developers: Volumes 1 & 2 - Technical leadership and communication
2 Books"Software Architecture for Developers" is a practical and pragmatic guide to modern, lightweight software architecture, specifically aimed at developers. You'll learn:The essence of software architecture.Why the software architecture role should include coding, coaching and collaboration.The things that you really need to think about before...
Django for Beginners/APIs/Professionals
3 BooksBuy every PowerShell book from Adam Bertram at a 20% discount!
CCIE Service Provider Ultimate Study Bundle
2 BooksPiotr Jablonski, Lukasz Bromirski, and Nick Russo have joined forces to deliver the only CCIE Service Provider training resource you'll ever need. This bundle contains a detailed and challenging collection of workbook labs, plus an extensively detailed technical reference guide. All of us have earned the CCIE Service Provider certification...
Cisco CCNA 200-301 Complet
4 BooksCe lot comprend les quatre volumes du guide préparation à l'examen de certification Cisco CCNA 200-301.
All the Books of The Medical Futurist
6 BooksWe put together the most popular books from The Medical Futurist to provide a clear picture about the major trends shaping the future of medicine and healthcare. Digital health technologies, artificial intelligence, the future of 20 medical specialties, big pharma, data privacy, digital health investments and how technology giants such as Amazon...
Linux Administration Complet
4 BooksCe lot comprend les quatre volumes du Guide Linux Administration :Linux Administration, Volume 1, Administration fondamentale : Guide pratique de préparation aux examens de certification LPIC 1, Linux Essentials, RHCSA et LFCS. Administration fondamentale. Introduction à Linux. Le Shell. Traitement du texte. Arborescence de fichiers. Sécurité...
Software Architecture and Beautiful APIs
2 BooksThere is no better way to learn how to design good APIs than to look at many existing examples, complementing the Software Architecture theory on API design.
Learn Git, Bash, and Terraform the Hard Way
3 BooksLearn Git, Bash and Terraform using the Hard Way method.These technologies are essential tools in the DevOps armoury. These books walk you through their features and subtleties in a simple, gradual way that reinforces learning rather than baffling you with theory.
9 Books-Bundle: Shut Up and Code!
9 Books"Shut up and code." Laughter in the audience. The hacker had just plugged in his notebook and started sharing his screen to present his super-smart Python script. "Shut up and code" The letters written in a white literal coding font on black background was the hackers' home screen background mantra. At the time, I was a first-year computer...