Knowledge exploration and exploitation

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 explores the concept of living documentation. The third chapter introduces knowledge management practices.

Find knowledge

Martraire gets serious in this chapter, whose first page recommends:

Identify all the places where authoritative knowledge is located. (p71)

When I first read this sentence, I didn’t stop to consider the implications. Even if you ignore the tacit knowledge that only resides in people’s heads, attempting this task encompasses much of knowledge management. I’ve worked with people whose whole job focused on this single problem. Even so, it gets harder than this.

Curate knowledge

Authoritative knowledge - each single source of truth - includes every unduplicated artefact. For example, Martraire mentions that:

Knowledge about how the software works is in the source code. (p72)

Software developers tend to prioritise avoiding duplication over other considerations, sometimes excessively. Even non-code artefacts will avoid duplication, if programmers had anything to do with them. As a result, a system’s authoritative knowledge might make up most of its artefacts, and a big consolidation problem.

When the knowledge is spread over many places, you need a way to do a consolidation of all the knowledge into one aggregated form. And when there is an excess of knowledge, a careful selection process—a curation process—is essential. (p72)

In practice, then, finding knowledge may lead to the harder problem of curating an overwhelming ‘excess of knowledge’ representations. And then it gets harder again.

Extract knowledge

Once you’ve identified and selected the knowledge that will help people understand a system, your next step makes it accessible. Martraire continues:

For a given need, set up mechanisms such as automation to extract the knowledge and transform it into an adequate form. (p71)

Finding knowledge and curating it sound like a lot of work; automating this extraction and transformation leads to a new difficulty level. In 25 years of professional software development, I’ve worked with a lot of smart people, and I don’t think I’ve ever seen any of them achieve this.

Pivot to sharing your solution

More focus on automated knowledge extraction wouldn’t have helped us, according to Martraire, who recognises the risk that programmers tend to lock on to the coding part of solving a problem:

Make sure this mechanism remains simple and does not become a distraction. (p71)

This sounds like a contradiction to me, because simple solutions require a lot of focus and many attempts, in my experience. While this idea of simple automation intrigues me, I also find it a little depressing to have never experienced it. Perhaps other software development teams do better.

Despite my pessimism, I consider this a worthy challenge, even if it requires not Kennedy’s determination, but the naive optimism enshrined in the programmer’s motto:

We do these things not because they are easy, but because we thought they would be easy.

I conclude that a team who achieves the level of knowledge exploitation that Martraire promotes has probably unlocked more value than they originally set out to achieve. They should pivot their company to help the rest of us with knowledge exploration and exploitation! Meanwhile, perhaps the best way to make this outcome more likely - maximising the number of attempts - involved writing a book about it.