Sometimes Complexity is Not Your Friend

In technical writing you want to avoid writing complexity. Narratives should be as clean and straightforward as possible, without leaving out any important information. Clean and straightforward is particularly important when addressing complicated topics.

Think how a reader approaches a manual or a report. A very few will read it from front to back. The rest will scan it, trying to pick out needed information without necessarily committing to an in-depth study. This presents particular challenges to document design.

Because I cannot count on my readers going straight from A to B to C, I find it works well to divide information into chunks. Ideally there will be no more than one fact per sentence, one full idea per paragraph, and once concept per page, or two-page layout, if it needs more room. Supplementary information such as definitions, explanations, and examples can be placed in call-out boxes or sidebars, visually separating them from the rest of the page.

By chunking information into page-sized pieces, the user can review exactly what they need to know without flipping back and forth (or in the case of screens, scrolling). This also forces me to concentrate on the meat of my presentation, leaving out the clutter of extraneous detail (think of the call-out box as the plastic storage bin of information design).

I also have to consider document navigation. There should be descriptive headings and subheadings, of course. The table of contents should be comprehensive and reflect the structure of the document. An index must, above all things, be useful. I’ve seen computer-generated indexes that cross-reference every noun in the document, without any indication as to which are the important ones. If necessary, add a glossary of definitions, and if your document is acronym-heavy, a separate list of acronyms and their definitions.

If your document describes a sequence of actions, such as how to set up a laser-cannon emplacement (first, check area for Ewoks) or how to run a political campaign (first, check constituents for Ewoks), “breadcrumbs” are handy. Breadcrumbs are a visual cue that lets the reader know where they are in the sequence. When the reader is trying to look something up later, they may remember that the information was in the green-tabbed section, or somewhere after Step 2 but before the chafing dishes are removed from the buffet.

It can be useful to add cross-references when necessary. Don’t feel at all shy about mentioning that the discussion of optimizing pixel size is on page 3-11, and the complete technical specifications of the Wonkaville Golden Ticket are included in Attachment F.

And lastly, beta readers. One difficulty with technical writing is that the writer has to be come temporarily an expert in the topic, and it’s easy to get lost in the weeds. A fresh beginner’s eye is the only way to identify critical gaps in logic or presentation. I usually tell my beta readers, “Tell me where it sucks, tell me where it’s confusing, tell me what you don’t understand.”

Aspen Junge