Improving the Readability of Your Docs

by Patrick Hofmann, Feature Writer

Growing up on a hog farm, one of my memorable encounters with user manuals and technical documentation was with, of all things, herbicide instructions. To ensure my family applied these herbicides responsibly—and didn't harm ourselves, neighbouring crops, and the environment—the instructions we read were spotted with countless cautions and warnings.

Furthermore, the instructions were extensive and complicated, as the mixing, spraying, and storing instructions had to accommodate numerous conditions like air temperature, humidity, wind, soil moisture, accompanying chemical mixtures, and the growth stage or timing of the crops and weeds, to name a few.

More than just the herbicide is a killer

Obviously, these factors still exist in herbicide instructions today. But surprisingly, little has changed in the way these instructions are written and formatted. While our software and hardware manuals have evolved by leaps and bounds, the good ol' herbicide guide has not. After all, these guides begin as regulatory documents that are sent to various government agencies—such as health, environment, and rural affairs—who review these documents before approving and registering the herbicide to be sold and used. For some reason, after the product is approved, these regulatory documents often undergo few changes before they are distributed to retailers and farmers as an end-user guide. Since these documents aren't written nor organized with the ultimate end-user in mind, they are incredibly hard to use.

But all is not lost. Even by applying a few basic rules of effective document layout, we can dramatically increase the readability and usability of such instructions.

Chunk the Information

I extracted the following paragraph from a herbicide manual (and changed the product name to protect the innocent). It contains three different scenarios on when to add water after applying a herbicide. Naturally, it should be chunked into three separate paragraphs.

BEFORE

AFTER

To amplify the chunking, apply bolding to the key "if" statements or conditions, so that readers can identify the relevant "chunks" more effectively as they are scanning through the section.

Add Visual Cues

In the example above, since the two "if" conditions have particularly different instructions than the "default" or introductory instruction, add an exclamatory visual cue to draw readers to them. If the document contains many such exceptions or conditional instructions, it may be helpful to visualize these distinctions in a "thumbnail" instruction, as shown in the top right.

Likewise, to help readers can through many chapters or sections whose content appears similar, apply a visual cue to the chapter or section heading. In the example above, I added a water-drop symbol to the Moisture Requirements heading, to distinguish it from the neighbouring tank mix, storage, and application requirements sections, and make it easier for readers to scan through the document.

Enhance the Typography

You'll notice quite a few typographical enhancements in the above "After" example to make the instructions easier to read:

• Remove the full justification and simply left-justify
• Apply an easier-to-read font. In the example above, I used Trebuchet MS - now readily available by default on both Windows and Mac.
• Increase the line spacing (the distance from one of line of text to the next) by an extra 1 or 2 points above the default line spacing. In the 10-pt. text above, I used 14-pt. line spacing instead of 12-pt.

Clean up the Tables

In the following table, farmers want to know what other herbicides they can mix with their current ACME herbicide, and at which growth stage of the crop they can apply it. If they are looking first for a particular herbicide, they have to find it in a list that is not in alphabetical order. If they are looking first for a particular growth stage, they have to read the column headings, move down to the cryptic Xs then move left to the applicable herbicide names.

BEFORE

AFTER

In the improved version, I have dramatically reformatted the table by removing the entire "X" concept, and merely organizing the applicable tank mixes according to growth stage. Although this may force some farmers who are looking first for a particular tank mix to read through the whole table, they'll be able to do so more quickly in this table.

To make the important footnotes and corresponding numbers easier to read, I applied enlarged and encircled footnote numbers directly to the tank mix names. This dramatically reduces the amount of eye-wandering caused by the Xs in the "Before" table.

To reduce the table's "visual traffic", I've canned most of the line segments that separate the table cells and agitate the eyes. Since each column is treated as a list of tank mixes, I've included merely a column separator, some shading in the table headings, and a bottom line to separate the table from the footnotes.

But what about the writing?

As you can see in the examples above, I haven't edited the writing in any of them! I've only chunked the information, added visual cues, enhanced the typography, and cleaned up the tables. Although editing and downsizing the wordy text will undoubtedly improve the usability by magnitudes further, the visual enhancements are a good start to eradicating many problems—just like the herbicides that are being documented!

About Patrick Hofmann

Patrick is an Interaction Designer at Quarry Integrated Communications 
in Waterloo. Although he's a rather vibrant speaker, his specialty is using illustration and visual language to communicate. When he's not trotting around the globe teaching the virtues of visual instruction and design, he conducts a 15-piece Swiss polka band in rural Milverton, Ontario. Who says tech-comm and trumpets don't mix?