Interview with Cyrille Martraire on the Living Documentation Book

Key points to remember

  • Documentation means the transfer of knowledge between people, but does not have to be written
  • Conversations are (often) more important than documents or documentation of conversations
  • Most, but not all, of the knowledge worth sharing is already somewhere in the system itself, but not necessarily in the most practical form.
  • The best place to store documentation is on the documented thing itself, for example by putting annotations on code elements
  • Living documentation can help a team improve system design and adopt Domain-Driven Design (DDD)

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

For Martraire, documentation is a matter of knowledge. We extract and transfer knowledge from conversations with other people, but we also acquire knowledge from “conversations” with our computers; we write code and run tests that pass or fail, and we use an application’s user interface and check the response. Observation is a third way of acquiring knowledge; you learn by watching how people work and behave in different situations and listening to their conversations with others.

Knowledge is necessary to avoid wasting time finding answers to questions that we should already know the answer to. Knowledge is also needed to avoid suboptimal decisions that could potentially lead to technical debt and increased system development and maintenance costs. Martraire points out that most knowledge is already there — in the source code, in the tests, in the behavior of an application, and in the brains of everyone working on it. It’s all about finding it and exploiting it.

In the first part of the book, Martraire describes the four fundamental principles of living documentation — that is, reliableit requires little effortEast collaborativeand insightful. Living documentation allows developers to focus on doing better work, while creating documentation.

In several chapters, Martraire describes ways to extract the important parts of knowledge from a system and how to create documentation, including traditional-looking documents, that are always up-to-date with minimal additional cost. Since a living document must evolve at the same rate as the system, it is normally created by automation. Annotations and conventions are two approaches that allow this. A glossary of terms used in part of a system is an example document that can be automatically extracted from the source code. Knowledge and documentation can also be created from a running system. To better understand a domain, developers working on an application should use the application and learn about its behavior 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 to understand exactly how the system is performing.

In the following chapters, Martraire discusses how living documentation can help with system design and architecture, especially for teams practicing evolutionary architecture where the architecture is constantly evolving. For DDD teams having trouble generating a living glossary or other business-related documents, this is a warning sign that their way of working with DDD is incorrect and the code needs to be redesigned to better reflect the business domain. When using the techniques described in the book, teams often begin to see further design improvements. Documenting decisions can often reveal weaknesses and encourage more thought and better design.

Martraire finally provides advice on how to introduce living documentation into a new environment and ways to document legacy applications. When introducing living documentation, he often recommends a soft, slow start, without asking permission. Instead, documentation should gradually become a natural part of a developer’s day-to-day work. Legacy applications are often very useful, but knowledge about them is usually not readily available; they may lack testing and there is no clear definition of behavior. To overcome this, Martraire describes a few techniques that apply, especially for legacy systems.

InfoQ: Tell us a bit about the book

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

The book therefore speaks of effectively sharing knowledge, of being more efficient, collectively and in the long term, in the creation and evolution of software. Which means the book is also a software design book in disguise.

InfoQ: Why did you decide to write the book?

Martyr: 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 this in a structured way.

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

Martyr: The book is aimed at software professionals who are not afraid of small amounts of code, so it is ideal for technical managers, code architects and automation testers. They will learn how to do documentation in an original way, without writing a lot of prose, with fun techniques to apply. But some readers tell me they learned more than that!

InfoQ: Do you see business value in living documentation?

Martyr: Yes, it is to expedite the delivery. Too much time is spent on software teams rediscovering how this software was designed, what it does, and how to evolve it consistently.

InfoQ: What do you think are the main benefits for teams or organizations that adopt living documentation?

Martyr: They work faster, as I just mentioned, and they also limit software degradation. When we know how something was designed, we are able to respect its design, or modify it knowingly. It is empowering. And there’s something more: once you’re careful to document what you do, you tend to do it better. It matters a lot!

InfoQ: What do you see as the main challenges?

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

InfoQ: When working with living documentation, you’re pretty close to the code base. Can domain experts and others outside the core team help adopt and maintain dynamic documentation?

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

InfoQ: Do you see a need or benefit for libraries with annotations recommended or perhaps included in a language or platform, for example a DDD annotation library?

Martyr: There would be a clear advantage for such a reusable library, provided you could create one that matches everyone’s particular flavor of programming and their specific technologies. So far, I would suggest creating your own library within your company, department, or team. If you are into functional and DDD programming in Java, for example, you would have your own library of Java annotations. But if you’re in Event Sourcing with an annotation-based framework, a lot of annotations are already there, you don’t need to add many. And if you don’t do all of that, then a library for all of that would seem pretty weird to your team.

InfoQ: Do you think living documentation will ever be common in the software community?

Martyr: The techniques will certainly become widespread, the only question is whether the name “Living Documentation” will ever become mainstream. But that’s a side issue 🙂 (laughs)

InfoQ: What do you think are the main reasons hindering the adoption of dynamic documentation in the software community?

Martyr: Documentation in general has been a neglected topic for ages. Additionally, the agile manifesto has often been misinterpreted. He never said not to do documentation. But the techniques to reconcile the objectives of the documentation with the agile values ​​are little known. The book aims to bridge that gap!

About the author of the book

Cyrille Martaire is a well-known authority on domain-driven design and software know-how and is a regular speaker at major international conferences. With in-depth knowledge of capital market finance, he has worked on and led several important projects. He is CTO and co-founder of Arolla, a French consulting company specialized in software development.

Sam D. Gomez