Change Reactivity

The documentation system tenet of change reactivity states that the documentation system should automatically detect and react to content changes by updating content, linking to new versions, highlighting deltas, or a combination thereof. This tenet supports the principle of truth proximity, and particularly, time proximity.

This adherence to this tenet is also assumed by the tenets of composability, and embedding and blending. Whenever a document part, or an embedded asset changes, the document view must change automatically, both during authoring and in a final rendering context.

For example, if a business analyst updates a LucidChart diagram, the new updated version should be reflected in all document views in which they appear. The same applies to drawings created with other applications, as well as text or any other content media type.

The veteran DevOps practitioner wouldn’t be mistaken by observing that this tenet is no different than the principle of running a build pipeline whenever new source code is committed to a repository; however, implementing a ‘git commit hook’, while a solution for version-controlled assets, covers only a subset of the applicable use cases.

Traditional DevOps practices take for granted that all software is maintained in a source code management system such as GitHub. This is often not true for documentation content. Forcing users to commit content to a source code management system—just for the sake of having a central point in which to run automations—would create an additional task for users, resulting in the violation of the principle of low cognitive load. The need for change reactivity applies right from the start of the authoring workflow, so documentation systems require a real-time previewing capability before documents are committed to publishing. 

Moreover, the canonical assets that are embedded in a document may come from a wide variety of external systems and be stored in a variety of media formats. Therefore, the DocOps engineer must consider multiple ‘change watching’ strategies depending on the nature of the external sources and the type of content it generates.

While simply updating documents with the newest version of the canonical asset is the most common behavior, this is not necessarily the one that applies to all use cases. Sometimes we want to reference a document part or embedded content by version because if someone were to update the canonical asset inadvertently, the document would then refer to ‘the wrong thing’. In other words, sometimes content parts and the composite documents in which they appear travel ‘together’ from a versioning perspective.

In cases like this, what we want is to alert users that a new version is available. In some other cases, we may want to be a little more helpful by highlighting the deltas between the current version and the version that has been just updated.