Q&A with Cyrille Martraire on the Book Living Documentation

In the book Living Documentation, Cyrille Martraire argues that we should rethink how we work with documentation when building software systems — we should embrace documentation that evolves at the same pace as the code. Traditional documentation is for him a boring topic, and often a source of frustration. One problem is that you often can’t trust it — the information you need is either missing, obsolete or misleading. In the book, he describes the concepts and ideas that are the base for living documentation and uses practical examples on how documentation that is always up-to-date can be created.

For Martraire, documentation is about knowledge. We extract and transfer knowledge in conversation with other people, but we also gain knowledge from "conversations" with our computers; we write code and run tests which succeed or fail, and we use the UI of an application and verify the response. Observation is a third way of gaining knowledge; you learn from looking at how people work and behave in different situations and listen to their conversations with others.

Knowledge is necessary to avoid wasting time on finding answers to questions we already should know the answer to. Knowledge is also needed to avoid suboptimal decisions which could potentially lead to technical debt and increased cost of developing and maintaining a system. Martraire points out that most knowledge is already present — in source code, in tests, in the behaviour of an application, and in the brains of all the people working on it. It’s basically a question of finding it and exploiting it.

In the first part of the book, Martraire describes the four core principles of living documentation — it is reliable, it requires low effort, is collaborative, and insightful. Living documentation enables developers to focus on doing a better job, at the same time as getting documentation created.

In several chapters, Martraire describes ways of extracting the important parts of knowledge from a system, and how to create documentation, including traditional-looking documents, that is always up-to-date with minimal extra cost. Since a living document must evolve at the same pace as the system, it is normally created through automation. Annotations and conventions are two approaches that enable this. A glossary of terms used within a part of a system is one example of a document that can automatically be extracted from the source code. Knowledge, and documentation, can also be built from a running system. To better understand a domain, developers working on an application should use the application and learn about its behaviour for most standard use cases, even in complicated domains. Inspecting a distributed system in real time and aggregating traces into a service dependency graph can also be a great help for architects in understanding exactly how the system works.

In the later chapters, Martraire explains how living documentation can help with the design and architecture of a system, especially for teams practicing evolutionary architecture where the architecture is constantly evolving. For teams into DDD that have problems generating a living glossary or other documentation related to the business, it’s a warning sign that their way of working with DDD is incorrect and that the code should be redesigned to more closely reflect the business domain. When using the techniques described in the book, teams often start to see other design improvements. Documenting decisions can often reveal weaknesses and encourage more thinking and a better design.

Martraire finally provides guidance on how to introduce living documentation in a new environment and ways of documenting legacy applications. When introducing living documentation, he often recommends a gentle and slow start, without asking for authorization. Instead, documenting should gradually become a natural part of a developer’s daily work. Legacy applications are often quite valuable, but the knowledge about them is typically not readily accessible; they may lack tests and there is no clear definition of the behaviour. To overcome this, Martraire describes a few techniques that apply, especially for legacy systems.

InfoQ: Tell us a bit about the book

Cyrille Martraire: The book is the result of many years of collecting ideas and trying things around documentation in an agile environment. Documentation has always been a source of frustration for everyone in software development. It’s never "like it should be", whatever that means. It’s time we solve this matter with concrete and applicable answers, so we can all live in peace about it, and be more effective about making software at the same time.

So the book is about sharing the knowledge efficiently, to be more effective, collectively and in the long run, in making and evolving software. Which means that the book is also a book about software design in disguise.

InfoQ: Why did you decide to write the book?

Martraire: The trigger for writing the book was the enthusiastic feedback after my talks where I mentioned some unfamiliar documentation techniques. As a software developer in many companies, I had spent many years experimenting with documentation techniques to make good software design more visible, and to encourage better design. The book was a natural conclusion to share that in a structured way.

InfoQ: Who are the intended readers and what can they expect to learn?

Martraire: The book is for software professionals who are not afraid of small amounts of code, so it’s ideally for tech leads, coding architects and automation testers. They will learn how to do documentation in novel ways, without writing much prose, with techniques that are also fun to apply. But some readers tell me they learnt more than that!

InfoQ: Do you see a business value in living documentation?

Martraire: Yes, it’s about accelerating delivery. Too much time is spent on software teams rediscovering how this piece of software was designed, what it does, and how to evolve it consistently.

InfoQ: What do you see as the key advantages for teams or organizations adopting living documentation?

Martraire: They work faster, as I just mentioned, and they also limit the software degradation. When you know how a thing was designed, you’re able to respect its design, or to change it with full knowledge of the context. That’s empowering. And there’s something more: once you pay attention to documenting what you’re doing, you tend to do it better. That matters a lot!

InfoQ: What do you see as the key challenges?

Martraire: A first challenge in that documentation is that it is not the most exciting topic on the surface. But with living documentation it becomes much more fun, until it can become another problem in itself, as a new opportunity to procrastinate and to avoid doing your boring work.

InfoQ: When working with living documentation, you are quite close to the codebase. Can domain experts and others outside the team core help in adopting and maintain living documentation?

Martraire: It’s true that the practices of living documentation tend to favor putting the knowledge very close to the codebase, as the source of truth. However, "collaboration" is a key ingredient of a living documentation, so we propose many techniques to make sure that the relevant knowledge is accessible to everyone involved, especially to the non-technical people. For example, you have living glossaries and living diagrams generated automatically out of the code. So yes, it’s for everyone, not just the developer who commits the change into the codebase after a collective discussion.

InfoQ: Do you see a need for, or an advantage with, libraries with recommended annotations or maybe included in a language or platform, e.g. a DDD Annotation Library?

Martraire: There would be an obvious advantage for such a reusable library, provided you could create one that fits everyone particular flavor of programming and their specific technologies. So far, I’d suggest crafting your own library within your company, department or team. If you’re into Functional Programming and DDD in Java, for example, then you’d have your own library of Java annotations. But if you’re into Event Sourcing with an annotation-based framework, many annotations are already there, you don’t need to add much. And if you’re not doing all that, then a library for all that would look quite weird to your team.

InfoQ: Do you think that living documentation someday will be mainstream in the software community?

Martraire: The techniques will get mainstream for sure, the only question is whether the name "Living Documentation" will ever become mainstream. But that’s a secondary matter :) (laughter)

InfoQ: What do you see as the main reasons hampering adoption of living documentation in the software community?

Martraire: Documentation in general has been a neglected topic for ages. Also the agile manifesto was often misinterpreted. It never said not to do any documentation. But the techniques to reconcile the objectives of documentation with the agile values are not well-known. The book aims to bridge this gap!

About the Book Author

Cyrille Martraire is a well-known authority on Domain-Driven Design and software craftsmanship and is a regular speaker at major international conferences. With an extensive knowledge on capital market finance, he has worked in and led multiple significant projects. He is CTO and co-founder of Arolla, a French consulting company specialized in software development.