# Living Documentation ![rw-book-cover](https://learning.oreilly.com/library/view/living-documentation-continuous/9780134689418/ibis_generated_cover_thumbnail.jpg) ## Metadata - Author: - Full Title: Living Documentation - Category: #books ## Highlights ### Chapter 1: Rethinking Documentation - Beyond making use of technology, writing software is a lot about making decisions based on knowledge. When you don’t have enough knowledge, you have to make learning experiments and collaborate with other people to discover new knowledge. This takes time, which also means this knowledge is expensive and has value. Going fast is all about learning faster when you need new knowledge or about quickly recovering any prior valuable knowledge whenever there was some. - Because writing documentation is not fun and is done because it simply has to be done, it is often done arbitrarily, without much thinking. The result is a random brain dump of what the writer had in mind at the time of writing (see Figure 1.5). The problem is that such a random brain dump is not helpful to anyone. - Enterprise knowledge management solutions are the places where knowledge goes to die. - Knowledge that is of interest for a long period of time deserves to be documented. Knowledge that is of interest to a large number of people deserves to be documented. Knowledge that is valuable or critical may also need to be documented. - The term living documentation first became popular in the book Specification by Example by Gojko Adzic. - Stigmergy is already the prominent way we exchange knowledge between the people and the machines involved when doing software. One key idea of living documentation is to acknowledge that this stigmergic effect is there, and to find ways to push it to the max. This starts by getting most of the knowledge out of the system you’re in, like ants do. - There is no need to record a piece of knowledge when it is already recorded in the system itself. - Every interesting project is a learning journey that produces specific knowledge. We usually expect documentation to give us the specific knowledge we need, but the funny thing is that all this knowledge is already there: in the source code, in the configuration files, in the tests, in the behavior of the application at runtime, in memory of the various tools involved, and, of course, in the brains of all the people working on it. - In a software project, most of the knowledge is present in some form somewhere in the artifacts. It is similar to ants learning how to evolve their nest mostly from the nest itself. - Therefore: Acknowledge that most of the knowledge is already in the system itself. When needed, identify where it is located and exploit it from there. - You’ve probably seen pictures of the Google datacenters and of the Centre Pompidou in Paris (see Figure 1.9). They have in common a lot of color-coded pipes, with additional labels printed or riveted on the pipes themselves. On the Pompidou Center, air pipes are blue and water pipes are green. This logic of color-coding expands beyond the pipes: Electricity transport is yellow, and everything about moving people is red, including the elevators and stairways. - This logic is also ubiquitous in datacenters, and even more documentation is printed directly on the pipes. There are labels to identify the pipes, and there are arrows to show the direction of the water flow in them. In the real world, such color-coding and ad hoc marking are often mandatory for fire prevention and firefighting: Water pipes for firefighters have very visible labels riveted on them, indicating where they come from. Emergency exits in buildings are made very visible above the doors. In airplanes, bright signs on the central corridors document where to go. In a situation of crisis, you don’t have time to look for a manual; you need the answer in the most obvious place: right where you are, on the thing itself. - In Situ Documentation - Internal documentation, also an in-situ documentation, means documentation that is “in the natural or original position or place.”10 ### Chapter 4: Knowledge Augmentation - When putting annotations within code is not possible, you can put them into a file next to the code. Sidecar files—also known as buddy files, companion files, or connected files—are files that store metadata that cannot be supported by the source file format. For each source file, there is typically one associated sidecar file with the same name but a different file extension. - Even though its use is not widespread, literate programming is still alive today, with tools available for all good programming languages, including Haskell, Clojure, and F#. The focus now is on writing prose in Markdown, with snippets of programming language inserted. In Clojure you use Marginalia,5 in CoffeeScript you use Docco,6 and in F# you use Tomas Petricek’s FSharp. Formatting.7 - A good example of commit guidelines is the Angular commit guidelines,10 which specify strict rules for how the commit messages must be formatted. These rules, says the Angular website, lead “to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the AngularJS change log.” According to this particular set of guidelines, the commit message must be structured as a header section, an optional body section, and an optional footer section, each separated by a blank line, as shown here: ### Chapter 6: Automating Documentation - Some problems are difficult to explain with words but are much easier to explain with a picture. This is why we frequently use diagrams in software development for static structures, sequences of actions, and hierarchies of elements. - Therefore: Whenever a diagram will be useful for the long term—for example, if it has already been used several times—you should set up a mechanism to automatically generate the diagram from the source code without any manual effort. Have your continuous integration trigger it on each build or on a special build that is run on demand at the click of a button. Don’t re-create or update the diagram manually each time. - Conversations and diagrams are not incompatible. Always being able to refer to the latest version of a diagram that reflects the current state of the software is a catalyzer of discussions. - Why do so many engineers think complicated system diagrams are impressive? What’s truly impressive are simple solutions to hard problems. - The ultimate rule of thumb: if there is at least one line crossing another in a diagram, the system is too complicated.