Principle of Truth Proximity

The DocOps principle of truth proximity states that documentation’s content should be as close as possible to its source in terms of time, content, and medium. In this sense, ‘truth’ refers to the prime form and origin of a given piece of information, rather than the veracity of facts expressed in it.

The motivation for this principle can be understood through a children’s game called Chinese whispers in the UK—telephone in the United States. In this game, children whisper a message from one to the other to see how much the message changes in the transmission. The more distorted the original message becomes, the more amusement it causes.  

Most enterprise documentation suffers from the Chinese whispers problem because it often includes content that originates elsewhere—outside the document itself. Many times, the origin of said content parts are in themselves based on other content parts. As such, the problem is not that ‘document X’ is out of date or incorrect, but that the sources it was based on, say, documents Y and Z might be incorrect, or out of date as well.

The degradation of communication during transmission was studied by Shannon (1949), who is the father of Information Theory. In Shannon’s model, introduced in his seminal paper ‘A Mathematical Theory of Communication’, a signal is subjected to a noise source when transmitted. Even though Shannon’s model was conceived in the era of broadcasting and telegraphy, we add our own ‘noise’ when reproducing information across different digital files.

An enterprise in which teams, departments, and domains create diverging versions of information is what Davenport et al. (1992) defined as “information anarchy”. In their study, they warned that “a firm cannot survive for long” when such information discrepancies exist.

Distortion is caused not only whenever a given piece of text is reworded. It occurs also when the content part to which the document refers changes while the document that refers to it does not. 

We will now delve into each constituent dimension of truth proximity: time proximity, content proximity, and medium proximity.

Time Proximity

Time proximity—also called timeliness or freshness—describes the likelihood of a document view reflecting the current state of the enterprise. It also describes how fast such a document view will change if such a state were to be altered. If time proximity is zero, then the document view is always up-to-date and there is no chance whatsoever that any of its constituent content would have changed without the document view changing as a result.

It is also worth noting that not all sources of information lend themselves to the ability of grabbing and refreshing ‘the latest version’ in real time. The likes of stock prices, exchange rates, weather patterns, machine sensor telemetry and so on take time to propagate. In the case of information provided by regulatory agencies, there may also be a process involved in obtaining updates which may hinder real time updates. From a DocOps point of view, the aim is to shorten the time between content changes and documentation view updates to the extent that automation technology permits it.

Content Proximity

In the context of time proximity, we assume that we have the right document part, except that it may not be the most recent. When it comes to content proximity, we are trying to ensure that we are pointing to the correct subset of content in the first place, and that we are faithful to the content’s structure, when relevant. 

Medium Proximity

Finally, we also violate—or considerably distance ourselves from—truth proximity when we irreversibly change the medium that supports a given piece of content and lose traceability to it. The archetypical example is that of manually converting a vectorial image, say, authored using LucidChart, and then exporting a bitmap version of it so that it can be pasted onto a document. Once this is done, there is no way to get back to the original LucidChart document to modify the image or obtain a higher-resolution version of it.

An irreversible change of medium is usually one of the greatest ‘offenders’ in substandard documentation systems because timeliness is nearly always broken as a result; whenever the original version changes, someone has to update the converted version manually. On top of that, it hinders collaboration, because the converted version is nearly always non-editable.

Achieving medium proximity doesn’t mean that we should simply ‘attach’ or ‘hyperlink’ files so that the medium is preserved. Contemporary documentation systems require embedding and blending all media types—video, audio, images, and text—to achieve a seamless user experience. The point is that we should still be able to trace the converted assets to the original medium so that the converted assets update themselves whenever the originals do, and that we enable co-creators to edit the source files by initiating the authoring workflow directly from the place where the embedded content appears. 

In other words, medium proximity is about narrowing the gap between where the content part is created and where the content is projected or rendered.

Reflection

Truth proximity is essentially the principle that sets the travel direction for the effective embedding of content in composite documents. It is not a relevant principle for one-off write ups which are never reused nor referenced. 

The below figure helps illustrate the interplay of the truth proximity dimensions—time, content, and medium proximity—by presenting three different versions of a document, each highlighting the problems surrounding non-zero proximity in each dimension.

In the first document view, time proximity is greater than zero because there is a new version (3) of the underlying drawing in which the circle has now a hatch pattern while the old versions (1 and 2) do not.

In the second document, content proximity is greater than zero because the embedding directive grabs the shape found in the top left corner of the drawing, while in the new version, the authors have moved the circle to the top right corner. This means that the mechanism used to select this specific figure is too rigid.

In the last document, medium proximity is greater than zero because a converted version of the original figure has been used without any traceability to the original. The assumption here is that in the first two documents, the image is embedded by linking it directly to the original in SVG file—it might be converted to a bitmap format on the fly if the web browser or application cannot display SVG files directly—and that the edit link launches the relevant authoring application.

Based on this example, the below table illustrates the truth proximity for various scenarios:

In a contemporary—or DocOps-empowered—documentation system, truth proximity is a measure of the system’s composition and embedding capabilities as well as of their effective use by users. Take the capabilities suggested for a truth proximity score of 7 above. This is an arbitrary number to suggest that there might be more effective approaches other than the use of a CI/CD pipeline.

For example, a cloud drive hook can convert a PSD image (Adobe Photoshop’s proprietary format) as soon as users save a new file without requiring a ceremonial Git commit. Maybe such an approach would get a truth proximity score of 3 rather than 7. In short, the choice of any non-zero, positive number range for truth proximity is a DocOps practitioner’s choice.

While automation is key, we don’t want just a technocratic approach which ends up being hostile to humans. This takes us to our next and final principle.