The Importance of Documentation:
An Object Lesson in Technical Accuracy

by Opal Gamble, President

As technical communicators, we all concern ourselves with ensuring that the material we produce is as accurate as possible. We double-check our facts. We get SMEs (Subject Matter Experts) to review our drafts. Quality assurance may even test our documents.

We send those documents out, pleased that we've done everything we could to make sure the information is correct. Maybe we even indulge in a little back-patting for a job well done.

But what happens to our audience when our facts go awry?

Small Scale Problem

Well, in some cases, inaccurate documentation creates a few headaches and some frustration, but nothing too terrible. A few weeks ago, while visiting my boyfriend, his Dad hauled me aside and said "I've got a problem... help?"

He had purchased an iTrip for his new iPod, and he could not get the software to work. "These stupid instructions," he cried, waving a glossy pamphlet, "I followed them exactly, and it doesn't work!"

(Technical writer for a laser systems company... sure, I can fix an iTrip-iPod documentation problem. No leap there.)

As it turned out, the problem wasn't the documentation. Not at all. In fact, I'm just about willing to guarantee that the writer in charge of those documents had everything right: the problem was that the CD was missing one important .xml file (the play list, for those of you in the know).

Let's face it, though. No one ever cries for the blood of the person that created the CD... they yell at the technical communicator and those "damn instructions."

When Documentation Makes Your Ears Bleed

A larger example of documentation gone wrong comes from an acquaintance of mine, who was on a strict deadline and had to work very late into the night on a project.

Before embarking on this late night project, she reviewed the company's security system documentation and discovered that if the system went off in the middle of the night, the security company would call the police and the facilities coordinator for the company where she worked. Both parties would then be obligated to investigate the intrusion.

Come 2 a.m., my acquaintance decided it was time for a fresh cup of coffee, so she headed off to the kitchen. As she reached to put her mug on the coffee machine ledge, the alarm went off with a shriek that made her drop her mug on the floor and sprint for the passkey on her desk.

It is quite possible that she set a new land speed record that night.

As per the instructions in the documentation, she fled to the nearest exit, went outdoors, and allowed the door to lock behind her. Then, she let herself back into the building with her passkey, which should have reset the alarm by informing the system that an employee was present.

The documentation promised that this would take "a few minutes."

Ten minutes later, she was back in her cubical, the shrillness of the alarm still peeling paint off of the walls, reading the security system documentation in hopes that she would find the technicality that was keeping the alarm screaming. Her mind was filled with fear as she imagined facing not the police, who were surely on their way, but a grumpy co-worker who was hauled out of bed at 2:10 a.m. for a false alarm at the office.

A Few Discoveries

As it turned out, the problem with the documentation was three-fold:

1. It neglected to indicate that when the system was full arm the shutoff was good for two hours after the first passkey entrance, rather than the most recent entrance. In other words, if Schmoe entered the building at 12:05, and Mary entered the building at 1:20, the alarm would re-arm at 2:05 a.m., not at 3:20 a.m.
2. It was out of date, and indicated that the alarm went into full arm at 11 p.m. instead of 1 a.m.
3. It omitted details that the writer considered "too confusing" for his readers: a few minutes is 15; walking through the building while the alarm is still sounding triggers it again, and so on.

Now, while nothing bad happened to "me" (you saw that coming, didn't you?) as a result of this documentation snafu—I managed to get the alarm turned off eventually and I didn't lose my hearing—it did give me a jolt about the project I was working on.

What happens to my end user, when my documentation glosses over something or is unclear?

The police aren't going to show up and arrest my readers because the documentation led them astray; however, that doesn't mean they aren't just as mortified and furious about the error in laser system documentation as I was with the mistakes in the security system instructions.

That alarm has triggered me to create my own three-fold rule: For every documentation flaw you write, you will fall victim to three more.

Be careful with your documentation!

About Opal Gamble

Technical writer, web monkey, and general geek, Opal's wanted to be a tech writer since high school; she became a STC-SOC council member in 1997. A graduate of UW's co-op Rhetoric and Professional Writing program, Opal is a Technical Writer and (unofficial) web designer at Virtek. She also runs her own freelance business.

When she's not doing STC business, Opal participates in autocross events (with a hybrid car, no less!) and tries to cultivate a green thumb in her garden.