3 guidelines to improve writing technical documentation

Organize content around graphics

A while back, I worked in the technical documentation department of a large computer manufacturer that shipped about five thousand computers daily, each with a user manual. The manual’s purpose was to get the buyer up and running as quickly as possible and not call customer support for assistance. In fact, the company depended on those manuals to be effective — each call to customer service was an expense that impacted the company’s bottom line by millions of dollars.

I was part of the usability group that conducted formal, laboratory-based studies to determine how customers read the manuals and retained information. We’d bring subjects into the lab and ask them to perform tasks such as set up the computer and run programs. We observed them in a quantitative manner to determine how they used the manuals.

What we discovered is that subjects would peruse the manual quickly but consistently stop at a page that had an illustration. Thus, we adopted a documentation policy that any page in a manual that discussed a concept we wanted the reader to remember must have an illustration. Once the policy was implemented, the number of calls to customer support went down, which saved the company millions of dollars.

Illustrations draw a reader’s attention. Once a reader is focused on an illustration, they will read the text around that illustration. For example, in Figure 1 below, your eye probably goes to the photograph in the illustration first, and then you’ll read the text in the article to learn more.

In documentation, a reader’s eye is drawn to a photograph or illustration first, and then to the surrounding text to learn more.

The same dynamic is true for technical documentation. People tend not to read the text first; instead their eye is initially drawn to an illustration.

To write technical documentation that gets the reader’s attention and promotes retention, you must maintain the reader’s attention. Put a graphic on a page that’s relevant to a concept or process you want the reader to understand, and then write text around that illustration to reinforce the concepts presented in the illustration.

Visual structure improves text readability and understanding

Written language is composed of symbols, each of which serves a distinct purpose. Some represent alphabetic characters that combine to form words; others, like those in Chinese, directly signify entire words. Punctuation marks function as elements for structuring sentences.

Regardless of a symbol’s specific assigned meaning, it is fundamentally an image, and thus carries both visual and linguistic significance. For instance, a word displayed in a larger font on a page visually conveys greater importance. Numeric or dot-like characters at the beginning of sentences indicate their inclusion in a list.

The human mind undergoes a complex process to decode a seemingly random collection of symbols on a page into meaningful language. To capture and hold a reader’s attention, it’s essential to minimize the mental effort required for this decoding process. This means organizing words and sentences in a visually clear and structured manner to make the content easier to comprehend and more engaging to read. How the words appear on the page matters as much as what the words mean.

Figure 2 below shows how visual structure can make the content of a technical document more readable and easier to remember.

Visual structure can make a technical document more readable and easier to remember, even if the language is not decipherable.

Unless you can read Thai, the meaning of the sentence on the left is indecipherable. However, one can infer from the right side of the graphic that the text describes items in a numbered list, solely by the visual structure of the content and the use of numerals. (Granted, the viewer must be able to read Thai to fully understand the meaning of the text.)

Understanding the text on the right is easier than the one on the left because the text’s structure predisposes the reader’s mind to process that text as a list of items. To attract and maintain a reader’s attention in documentation, visual presentation of words and sentences on a page is just as important as the content’s meaning.

Figure 3 below shows the English version of the content displayed above. Our inference of a five-point list was correct.

As inferred, English translation reveals a five-point list about Kubernetes.

Avoid ambiguous use of pronouns and modifiers

When reading text, especially technical documentation, the human mind instinctively seeks to understand the relationships between words and phrases. Any ambiguity disrupts this process and leads to confusion and a potential loss of attention. To ensure clarity and maintain reader engagement, it’s crucial to minimize ambiguity, particularly when it comes to the use of ambiguous pronouns and modifiers.

Ambiguous pronouns

Consider the following sentence:  The thing to remember about using AI at the Edge is that the resources it needs to execute the LLM models are considerable.

In the phrase “the resources it needs,” it is unclear if the word “it” reference AI or the Edge.

Now, consider the revision:  The thing to remember about using AI at the Edge is that the device and network resources needed to execute the LLM models are considerable.

In the latter example, the reader does not have to figure out what a pronoun references, and so they can stay fully engaged with the content. When readers pause to determine a pronoun’s reference, their focus shifts away from the natural flow of the writing. The more energy the reader spends on resolving pronoun ambiguity, the less attention they can devote to understanding and appreciating the actual substance of the text.

Using pronouns can make written language more engaging and less repetitive, as it avoids the monotony of repeating nouns. However, there is a risk that pronouns can introduce ambiguity. The key is to use them judiciously.

Ambiguous modifiers

The following sentence is an example of an ambiguous use of a modifier:  The developer compiled the code in C++.

The modifier “in C++” is ambiguous: Was the code compiled using C++? Or was the code written in C++ and then compiled? The reader must interrupt their concentration on the text and instead determine the modifier’s target. That brief blip of distraction runs the risk of cascading into a significant loss of attention.

However, the following corrects the problem:  The developer compiled the C++ code.

Here, all is clear: the word C++ describes the code and not the compiler. The reader is not distracted and keeps attention focused on the text.

Putting it all together

Writing technical documentation is hard. Topics are complex and can be hard to grasp for many readers. Making a technical document clear and memorable requires more than just putting words and graphics in a document. To keep a reader’s attention it must be well-structured visually both in terms of graphics and textual layout, and with unambiguous language particularly around the use of pronouns and modifying words.

Utilizing the three principles for effective attention management described in this article will help technical writers create documents that minimizes cognitive distraction and keeps the reader’s attention. Well-crafted technical documentation is essential for those writers and companies that need to ensure that complex information is communicated effectively and efficiently.

Bob Reselman is a software developer, system architect and writer. His expertise ranges from software development technologies to techniques and culture.