My son once asked me why the sky was blue, and being a dutiful father, I told him. I started by casually mentioning light absorption and scattering, but that didn't satisfy him: he wanted to know why certain colors of light were absorbed, reflected, or scattered. So I explained how white light was made up of many different wavelengths, and that each wavelength was absorbed or reflected differently because of the physical properties of the molecules that make up our atmosphere. That didn't satisfy him either, so I dug a bit deeper. Each new answer generated yet another "why", and long before I invoked quantum mechanics and the interaction of light waves with electron orbitals, two things became clear: first, he was only asking out of stubbornness, since he'd long since ceased understanding anything I was saying, and second, I'd reached and surpassed the limits of my own knowledge. Eventually, I simply replied "because that's the way the universe is", an answer that relieved both of us.

True Lies

Fortunately for those of us who write and edit technical manuscripts, this level of curiosity and stubbornness is highly atypical; if it weren't, we'd never be able to complete a documentation project because we'd never finish discussing the quantum mechanics of the File menu. As my anecdote reveals, sometimes going beyond the first and simplest explanation provides too much detail only confuses our audience. This means that technical communication is one of the few types of writing where it's acceptable to lie to your readers--at least in the sense that providing only as much information as they need to know, rather than the whole truth, is lying.

Unfortunately, this raises the difficult question of determining just how much detail we must provide to fully satisfy our audience's need for information. Answering that question depends on understanding just how much technical accuracy is truly necessary. At some point, "because that's the way the universe is" becomes technically inaccurate, but satisfies the reader's need for information. Going beyond that point to provide a fuller explanation may be more than the reader really needs to know and may actually impede understanding.

So how do you pick the correct level of detail? Consider the product you're documenting from the viewpoint of your readers. To them, accuracy means three things:

1. Visual Fidelity
Visual fidelity means that what you describe in your documentation matches what viewers see in the product closely enough that they won't notice any distracting differences. If you say that a feature is present, it must be present--but it must also be present at the location you described, and must look the way you promised it would look. Moreover, the word labels that appear on it must be identical to the word labels you use in the text. But if the surface texture is brushed, anodized aluminum, and you use a simple metallic color in your diagram of the product, that's acceptable; the differences between the two textures are unlikely to distract anyone.

2. Correctness
Correctness means that readers should never encounter an experience that differs from the experience you described in your documentation. If a process takes five steps to complete, with specific details in each step, your description must contain exactly those details, and no others. If you explain that something works in one specific way, it must work that way, without exception. Where the possibility of deviation from your description exists, you must explain the circumstances that could cause the deviation, and whether readers should do anything about this deviation.

3. Completeness
Once you understand intimately how readers will use a product, you understand all the details you must explain to support that use. The thing that separates good technical writers from product designers is that we have the ability to use a product the same way its intended audience will use it; the designers are usually too close to their design to achieve this level of empathy, and already know all the things the product's users must be told. Providing an incomplete description means that readers must fill in the gaps themselves. Providing a fuller description than what they need to accomplish their tasks generally won't help them do their work; in fact, it may slow them down because they must first read the unnecessary information before they can decide whether it's truly necessary.

Lie to Them -- But Just a Little

Understanding these three factors lets you determine just how much technical detail readers require. For example, readers don't need to know that saving a file on their computer's hard disk really means translating the file into a series of magnetic domains imposed onto a thin film that can reliably store those magnetic domains for a limited number of years. That's certainly interesting to geeks like me, but entirely irrelevant to the reader who simply wants to understand their word processor's "Save File" command. In contrast, users of the original Macintosh computers needed to understand that the trashcan icon on their computer was actually an incinerator that eliminated trashed files as soon as they shut down the computer. (But as in my first example, they didn't need to know about the magnetic heads that erased the information from the disk.) In both cases, the level of accuracy required is the level that affects how the readers use the software--and nothing more. So in a very real sense, it's okay to lie to your readers by presenting them with only the information they need to know, even if there's more to be known. How to determine what they need to know is a matter for a future article.

Find Out More...

• 13 Tips on How to Tech-talk to Non-techies, by Hasmita Chander
  
  
• KISS - Keep It Simple, Sweetheart: How to Write About a Complex Subject in a Simple Way, by Devyani Borade
  
  
• Succeeding as a Technical Writer, by Michael Knowles