Book review — Living Documentation

This is a solid reference book, with a substantial content of 480 pages in a hard back cover. It has a picture of the pipes from the Pompidou centre in France on the cover, which is relevant due to the colour coding of the types of pipes which is an example of self documentation. Cyrille Martraire is a CTO and speaker at conferences on various aspects regarding software development. There is a lack of material in this area so this is a welcome addition to the bookshelf. It heavily references DDD Domain Driven Design, BDD Behaviour Driven Design and Java examples as well as a variety of tools that can be assembled to create a documentation toolkit. It is not a magic bullet and doesn’t include a secret sauce recipe, but it does explain a wide range of concepts and show real life examples which should help the reader start exploring areas further.

There are 15 chapters in this book:

• Chapter 1 — Rethinking Documentation — Great introduction to the topic of Living Documentation. It explains self-documentation, and how the principles relate and co-exist with AGILE, BDD and DD. The depth of the tables listing these concepts as patterns show the author knows his subject extensively.
• Chapter 2 — Behaviour Driven Development as an example of Living Specification — A lot shorter than chapter 1 but gives an introduction to Given-When-Then syntax from BDD and various tools such as Cucumber and Specflow.
• Chapter 3- Knowledge Exploitation– Explains sequencing of information flow and use of automation. Snippets of Java code start to appear as examples.
• Chapter 4 — Knowledge Augmentation — This chapter makes a lot of sense and describes additional sources of information either annotated inside the code or externally (in a database or sidecar file). The simple sidecar file eg algorithm.txt to support a code module algorithm.java that has a similar name is explained. Annotation and tags are described with heavy references to java examples.
• Chapter 5 — Living Curation: Identifying Authorative Knowledge — Concepts of sightseeing maps and identifying good code are revealed, along with consistency and naming conventions.
• Chapter 6 — Automating Documentation — A really useful section as it highlights some though provoking items. Such as a massive class diagram for all classes in a codebase, where as it is easier for the reader to just see a few related to the module of interest. A bit like looking at the entire world on a detailed map when you only want to drive up the road and being overwhelmed by the scale of it all. This chapter also covers hexagonal architecture diagrams as a different way to look at the world The examples of pictures produced by static tools that reverse engineer code were extremely interesting. This shows a general concept and examples without Java specific syntax.
• Chapter 7 — Runtime Documentation — Traffic tracing on distributed systems and event sourcing are explained as ways to augment knowledge from the system when it is running
• Chapter 8 — Refactorable Documentation — Code conventions, naming and types are covered in the realm of code as documentation.
• Chapter 9 — Stable Documentation — Stable and unstable information and how it can be documented. This allows a reader to consider refactoring a document eg readme.txt file to contain stable information and hence require updates less often.
• Chapter 10 — Avoiding Traditional Documentation — A variety of scenarios and example on techniques to try and avoid documentation through other routes e.g. conversations based on the value and duration of the information.
• Chapter 11 — Beyond Documentation — Living Design — Some good examples and tips in this chapter, including “shameful documentation”. The main message being when you make clear documentation the design becomes transparent. Has some really simple but effective ideas for crudely scanning code as a signature survey.
• Chapter 12 — Living Architecture Documentation — Good coverage of design and architecture, and reasons for decisions. Some good examples of ADRs, and architecture templates. Some pragmatic tips on minimising documentation using a codex. A really useful section with lots of hints and ideas.
• Chapter 13 — Introducing Living Documentation to a new environment — This is more managerial advice on how to introduce the concepts to a business. This feels like it has some solid experience behind it and tips learnt the hard way. It advocates starting gently and building up, which definitely feels like good advice. It even includes how to handle common objections. This managerial level is in contrast to the detailed java code snippets earlier in the book and shows the flexibility of the author.
• Chapter 14 — Documenting Legacy Applications — Covers annotation, augmentation and rearranging items to be more understandable.
• Chapter 15 — Extra : Conspicuous Documentation — Covers a lot of interesting items that don’t fit neatly in anywhere else. From low fidelity information and diagrams and their benefits, concrete examples of scenarios and problems to get real deep dive detail and tips on how to prepare for an interactive workshop. It also covers lot of other media and types of documents such as news, release notes, APIs. Again the shaded tip boxes work really well and draw the readers eye to salient points.

The 15 chapters flow easily and have been well considered. The titles are all generic and refer to Living Documentation in a wide sense, however code examples are in Java. There are a variety of hand drawn sketches through the book to lighten the mood, these don’t distract and are relevant to the areas they are placed. There are numerous easy to understand and believable examples, all the sketches are clear and appropriate and every topic feels like it has been thoroughly covered. There are shaded tip boxes and throughout the text hints to follow up for keen readers with specific books or papers on a topic. This is a great way to keep the flow going and the text to a sensible length but give signposts to avid enthusiasts on how they can find out more on a specialised area.

Summary

Having read this book I found myself taking notes as I worked through it because having scanned the book I couldn’t find key summaries. I was looking for a list of key information that I could refer to at a later stage as a full reference on Living Documentation, in particular:

• List of tools and websites
• List of books, authors and their topics There are numerous great links and tips scattered through the document but it would have been really helpful to have a condensed list in an appendix at the end of the book. There are a lot of examples with Java in this book, perhaps too much java or at least not enough generic description of ideas and concept before a practical example in Java. As there are relatively few books on the Living Documentation topic area this one stands out, so is a great reference piece. It could have been titled “Living Documentation for Java Programmers” which reflects how it is written. Living Documentation with some Java Examples would have been better or even Living Documentation A Complete Reference but it wasn’t to be.

No matter, these are minor points as this is an excellent document and key reading for anyone interested in the subject area and the bonus is it an easy read, light and airy in style but deep in content. Due to the lack of other books this one stands out and I was enthused and invigorated by reading it. I have no hesitation in recommending it, and hope if it is ever revised then there is opportunity to make it really great and a handy desktop reference guide for everyone.

Details of Book on Living Documentation

Living Documentation by Cyrille Martraire June 2019
480 Pages
Published by Addison-Wesley
ISBN 978–0134689326
Buy on Amazon