Connected Content

The documentation system tenet of connected content states that all related information components should be connected, sparing the user from the need of parallel searches. This tenet supports the principle of low cognitive load by bringing content together in such a way that flow is maximized and content switching is reduced.

In Haeckel & Nolan’s (1993) three-prong Corporate IQ model, connecting is defined as “the degree to which the IT platform links information sources, media, locations, and users.”. In a body of documentation, the connections are more informationally meaningful than the content of documents in isolation. Connecting content is also more useful than categorizing content, as Bush (1945) explains: 

“Our ineptitude in getting at the record is largely caused by the artificiality of systems of indexing. When data of any sort are placed in storage, they are filed alphabetically or numerically, and information is found (when it is) by tracing it down from subclass to subclass. It can be in only one place, unless duplicates are used; one has to have rules as to which path will locate it, and the rules are cumbersome. 

Having found one item, moreover, one has to emerge from the system and re-enter on a new path. The human mind does not work that way. It operates by association. With one item in its grasp, it snaps instantly to the next that is suggested by the association of thoughts, in accordance with some intricate web of trails carried by the cells of the brain.” [emphasis added]

Later on, Nelson (1987) commented:

“The structure of ideas is never sequential; and indeed, our thought processes are not very sequential either. True, only a few thoughts at a time pass across the central screen of the mind; but as you consider a thing, your thoughts crisscross it constantly, reviewing first one connection, then another. Each new idea is compared with many parts of the whole picture, or with some mental visualization of the whole picture itself.”

Berners-Lee (1999), who introduced the modern form of what we understand as a ‘hyperlink’, gave key importance to the value of connections:

“In an extreme view, the world can be seen as only connections, nothing else. We think of a dictionary as the repository of meaning, but it defines words only in terms of other words.”

“There are billions of neurons in our brains, but what are neurons? Just cells. The brain has no knowledge until connections are made between neurons. All that we know, all that we are, comes from the way our neurons are connected” 

A customer of mine once asked me, in the context of authoring wiki pages, “What specific keywords do you think I should link in a page, Ernie?”. Before I could think about what to say, he answered himself. “…personally, I would link everything”. What he meant is that he would link any word that has a matching wiki page. He was right on the money. In a contemporary documentation system the reader should never find themselves baffled at an unfamiliar concept so that they end up copying keywords and pasting them in the search box to find out more. Content that is related should always be connected. As Bush concluded, in reference to the Memex’s key feature, “the process of tying two items together is the important thing.”

The hyperlink is not the only way to connect content, though—and text is not the only form of content and hyperlinks are not cognitive load-free either; whenever a hyperlinked word appears, the user is presented with a choice, “should I click this link or not?”, which breaks the reading flow. 

My view is that, in the context of enterprise documentation, connecting information and breaking silos is paramount and ‘hyperlink pollution’ might be the lesser evil, when contrasted to forcing the user to copy and paste the relevant text fragment to run a parallel search. Having said this, providing an ‘immersive reading experience’ feature—which disables all links—is straightforward to implement, using a simple CSS stylesheet. It is not harder than implementing a ‘dark theme’ theme, which is popular nowadays in most sites. 

Getting back to the issue of cognitive load, it is worth noting that while the mere presence of a hyperlink causes some level of distraction, clicking on it causes the reader to context switch away from the current document view. This is why, as we will learn in this section, connecting content is many times about bringing the content directly onto the relevant document view rather than just linking to it.

Another key point about this tenet is that connecting content does not amount to connecting ‘documents’. Whenever possible, we want to relate pointed information so that the connected content helps fill the specific knowledge gap at hand. In other words, we should avoid forcing users to read complete ‘related documents’, memorize them, and then return to the current document view.

Before we can connect content automatically, it is preferable to have a suitable documentation architecture that facilitates—or at least increases the accuracy—of matched content. We will first delve into this topic. After that, we will cover some of the most salient use cases:

• In-Image linking: connecting pictorial information with matching content.
  
• Auto-linking: automatic linking to matching content.
• Definition expansions: expanding abbreviations, acronyms and short definitions.
• Infoboxes: adding definitions without disrupting the reader’s flow. 
• Glossaries and footnotes: generating context-relevant lists of definitions.

Let’s now delve into each of them.

In-Image Linking

Most images used in enterprise documentation are pictorial representations of information. This means that the information conveyed by said images can be represented by other non-pictorial means—text, a table, a set of math identities, computer code and so on. In nearly all cases, said information is composed of multiple information subcomponents, each of which are likely to already exist in the documentation base. If so, they should be connected; the reader should be able to click on the boxes or ‘bubbles’ of an image, and find the relevant matching content.

The ability to link to the specific x, y coordinates of an image was supported in HTML as early as 1995 (Berners-Lee and Connolly), however, many documentation platforms do not tap onto such features; they only allow linking to the entire image rather than a subset of it. This is a serious problem. 

Most diagramming tools allow associating each figure—text box, rectangle, oval, etc.—with a hyperlink so there is no reason as to why enterprise documentation should be broken when it comes to images. Images in pure bitmap format for which there is no source are not a lost battle either; image maps can be created on top of them and labels can be identified using Optical Character Recognition (OCR). Facebook can match people’s faces with their profiles; this is a small feat for an enterprise that claims to have an information ‘technology’ department.

Auto-linking

Auto-linking is not a new concept and it is not hard to implement, but is surprisingly conspicuous by its absence in most documentation systems. 

Let’s first see how ‘regular’ linking works. In HTML, we create references using HREF anchors. In most wiki engines we link to other wiki pages by simply enclosing a word in one or more square brackets, like [[this]]. In visual editors we typically create a link by clicking on a chain-link looking icon and then selecting the target page. This workflow has never changed since the days of HyperCard in the Apple Macintosh. It predates the Internet. 

DocOps is obviously not about manual work. Keywords and text fragments that are unequivocally connected to relevant content should always be automatically linked without inflicting cognitive load on users by making them think whether there is matching content for every word they type. The same applies to images be it when text labels are identified via OCR, or when objects are automatically detected. 

Definition Expansions

So far, we have discussed auto-linking as an automated means to connect text fragments to relevant document views. While connecting information and breaking silos is DocOps’ bedrock, the quintessential web hyperlink is not always the right way to connect information. First, hyperlinks are meaningless in printed documentation—unless the target document view is embedded and referenced by section or page in the same document. Second, we may not always want to force the reader to context switch and digest an entire document view when it suffices to bring some context to the current document view.

In his famous May 2010 e-mail, with the subject line “Acronyms Seriously Suck” (Vance 2015), Elon Musk wrote:

“There is a creeping tendency to use made up acronyms at SpaceX. Excessive use of made up acronyms is a significant impediment to communication and keeping communication good as we grow is incredibly important.” 

Let’s face it, acronyms, abbreviations and outright cryptic terminology plague both business and technology communications. Even this very text—DocOps—uses an abbreviation as its title. However, there’s no need to burden authors with the spelling out of concepts for which agreed acronyms and abbreviations exist, nor readers with either the bufflement of finding new nonsensical terms, nor the cognitive load of context switching away to a new tab to find out more when they are linked. There is no need to pick a poison. We can do better, we can apply DocOps technology. 

Abbreviation, acronym, and definition expansion—simply an “expansion” from now—share the same text fragment ‘matching’ technology with auto-linking, the difference is that the outcome is not the adding of a hyperlink, but the insertion of text. 

The documentation platform should enable defining which words of key fragments may be expanded—in addition to being auto-linked. For example, in the following example, we have a paragraph, using the acronym BCD, before processing: 

Due to health and safety, once a BCD has been used underwater, we need to send it back to the manufacturer for refurbishment, if returned by the customer. The BCD inspection process sits within our customer returns and refunds team.

Then, after processing, having the acronym BCD configured for auto-linking and auto-expansion, but customer for auto-linking only, we have the following result:

Due to health and safety, once a BCD (Buoyancy Control Device) has been used underwater, we need to send it back to the manufacturer for refurbishment, if returned by the customer. The BCD inspection process sits within our customer returns and refunds team.

Infoboxes

Infoboxes (also called sidebars, boxouts, or ‘floats’) serve to provide additional information to a body of text without disrupting the reading flow.

An infobox is meant to be rendered automatically in the vicinity of keywords that trigger its appearance. As such, depending on the desired behavior, we may have one infobox per keyword, or a single infobox which consolidates all proximate matched keywords. 

An infobox also allows more flexibility than a definition expansion given that a longer narrative may be used which may also include markup and images. It is worth noting that an infobox is not necessarily a substitute for auto-links and definition expansions. It may be used in addition to them to provide more clarity on specific, important terminology.

Glossaries and Footnotes

In the web medium, we have the luxury of hyperlinks to provide ‘additional information’ whenever required. On paper-based render targets, though, adding long definitions or URIs adjacent to keywords can disrupt the reading flow. In such cases—and when there are an excessive number of terms to fit them into infoboxes—it may be more convenient to centralize all definitions and URI references into glossaries or footnotes, which may be referenced by number.

Such glossaries and footnotes can be generated automatically based on the effective presence of matching keywords. 

Content Recommendations

Content recommendations are a staple of a contemporary content digital experience. However, we have left this feature last in terms of connected content for two reasons.

First, an enterprise documentation system is not the place to deploy black patterns—i.e., clickbait mechanisms. We want knowledge workers to spend as little as necessary to get their job done in the confines of the documentation system. Second, we don’t want to direct readers to general ‘related articles’ but, rather, to pointed, highly relevant document views, which is what we do when we hyperlink, or expand keywords.

Automating content recommendations is similar to building automated glossaries in which we build an inventory of matching keywords found in a document view and then render the results all at once.

Content recommendations may also be based on navigation trails. For example, if most users who access the Customer (CRM) document view typically access the Customer (Billing) document view right after, they could be presented with the latter as a recommendation when browsing the former.