The Trivium of Technical Communication 🔺

I am increasingly convinced that the most effective communication or documentation is presented in three forms: Code, content, and diagram. I am not suggesting something as strong as a Curry–Howard correspondence but a very meaningful and necessary continuum exists between the three.

Let’s start with code and content. It’s long been understood that code should be self-documenting. One way to do this is to include snippets of natural language within the codebase that get parsed differently in order to produce human-readable documentation. The relationship works the other way as well. Do you remember the last really good tech talk you saw and how the speaker interspersed small snippets of code into the slides to demonstrate the things that were being discussed? It is to say that the clearest and most precise content should be precise enough to be formally modeled to some extent.

Famous cryptographer Nick Szabo has even made a distinction between wet code and dry code. If I’m following his thinking properly then a legal contract would be an example of wet code. It’s written to be rigorous, precise and without ambiguity but it still is, strictly speaking, a natural language. So even here the distinction between code and content is shown to be a continuum and not binary.

The distinction between code and content is even further being blurred by how effective we are becoming at generating content from code (GPT-3) and how our content is becoming increasingly structured with rich data (Wikidata). Even the structure and flow of narrative writing, and not just internal data points, is being driven by formal/executable tools with things like interactive fiction.

Let’s move on to the diagramming side of things. It is indeed true that a picture is worth a thousand words. In working with Software architects over the past few years I’ve noticed how much time we spent on creating diagrams. And, mind you, these diagrams are not created because they are required by anyone but because they are an invaluable tool in communication. Even in non-engineering contexts, diagrams are used extensively. Consider the impact of the snail with a tumor diagram on agile. I just spent a few days in a SAFe training class and a diagram was used to illustrate the entire core of the system.

Diagrams are a kind of compression for human cognition and memory. Humans are far better equipped for image recognition than any type of complex propositional processing. Competition memory masters know this and use it to their advantage by associating data sequences with geospatial realities. Often even constructing stories within those realities in order to retain huge amounts of information. This method is referred to as building a mind palace

The method of loci is a strategy of memory enhancement which uses visualizations of familiar spatial environments in order to enhance the recall of information. The method of loci is also known as the memory journey, memory palace, or mind palace technique. — Wikipedia

The desire for there to be an explicit correlation between code and visual diagrams explains the recent popularity of code-to-diagram libraries like Mermaid or even architectural languages like Ballerina that produce diagrams directly from the executable code itself.

So what is the takeaway? Only this, that if one can present new ideas using all three, code, content, and diagram, in the same body of content then you will be presenting your ideas and thoughts in the most information-rich way and the concepts delineated should have a higher likelihood of being compelling. I will be employing this line of thinking as I seek to redefine and expand upon existing agile scaling systems. Most of them contain a lot of content but few represent the prescribed workflows or processes as abstract models that can be executed as code or summarized in memorable diagrams. It’s my hope and goal to advance the agile ecosystem with more rigorous methods using some of these principles.