Martraire’s principles of documentation

1. Principles of documentation
2. Principles of living documentation
3. Knowledge exploitation
4. Knowledge augmentation
5. Curation and storytelling
6. Glossaries and data dictionaries

The book Living Documentation, by Cyrille Martraire, covers a wide range of software documentation topics. This article reflects on the scope the first chapter introduces.

Documentation as knowledge transfer

Martraire starts by defining documentation from the perspective of knowledge transfer (p17):

The process of transferring valuable knowledge to other people now and also to people in the future.

This frames documentation’s purpose as the result it achieves: that someone has knowledge the they wouldn’t have otherwise acquired. I’ve often felt like it took years at the start of my professional career to unlearn the implicit lesson from school that writing has no purpose other than proof-of-work. Too much schoolwork felt like proving to a teacher that I’d understood something, rather than sharing it.

Any discussion of documentation needs to make this outcome focus explicit, because schoolwork, ISO compliance, and other bureaucracies attach so much importance to the idea of documentation as an achievement in itself. After all, perhaps knowledge does want to remain secret, in its more power-hungry moments, but it also longs for the liberty that accessible documentation has. Information usually does want freedom.

Three principles of documentation

Having dealt with the documentation-as-goal straw man, Martraire moves on to reject the comprehensive documentation straw man. His principles of documentation continue the knowledge theme, by introducing the scope of documentation-worthy knowledge (p19):

• 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.

Conversations about software documentation, especially with programmers, risk touching on the fear of having to write a lot of documentation (instead of writing code). Any discussion of documentation needs the qualification that becomes obvious with experience: you don’t document most knowledge, and that you don’t actually spend much time on documentation. Or as Martraire puts it, ‘The Default Is Don’t’.

The fourth principle

While narrowing the scope of the documentation problem, we can add a fourth principle:

• Knowledge that you can recreate cheaply does not deserve documentation.

You can create knowledge more cheaply than documenting some kinds of information:

1. unpredictable information that changes more frequently than how often you need to use it, as for estimates and most kinds of predictions about the future
2. information that you need so rarely that it costs less effort to ask someone each time, such as an annual check on software whose support will end soon
3. raw information whose audience can interpret it directly, such as diagnostic log messages.

This principle of less documentation subtracts from the documentation I might otherwise recommend writing. Apparently, people systematically overlook subtractive changes. Perhaps that explains why software developers make excuses for not documenting more, instead of understanding how to successfully document less.