Technical Writing: It's Not as Easy as it Looks

By Doug Nickerson

Ever read the instructions for your cell phone or browsed the instruction manual that came with your microwave oven? This type of writing is called technical writing, and technical writers are creating more of it every day.

We all consume the stuff in our daily lives, in the workplace and at home. And while many readers are helped by this mountain of diagrams and prose, others are frustrated by it. Why?

Read the Manual

After an hour-long technical support call, a frustrated customer support person says under her breath, "read the manual, stupid." She may not actually think you're stupid. But she sure wishes you'd taken a look at the manual before picking up the phone.

Many users of a product avoid reading instructions like the plague. They will pick up the phone to call technical support before even attempting to look through the documentation for an answer.

Other readers of manuals read the introduction. They may even try a few of the tutorials if included. These readers will call for support only if adrift in particularly troublesome waters.

Some readers enjoy manuals and will read them cover-to-cover. And here we start to get a glimmer of why technical writing may be harder than it looks: A writer must write with these different audiences in mind.

But back to our first question: Why is the manual so bad?

The Nature of the Beast

Are there reasons inherent in the difficulties of creating useful documentation that lead to technical writing's reputation as something to shy away from?

I think there are-and I think they seem to fall in to four areas: inadequate management support, scheduling problems, specification changes during product development (software is famous for this), and the built-in difficulties of expressing instructions clearly.

Lack of Support

Sometimes management does not support a documentation effort. Perhaps they will not support as many manuals or as many pages as are needed. They may provide a manual only as an afterthought. It's fair to surmise that a manual provided as an afterthought won't be the best manual.

Scheduling

Scheduling problems show themselves when a writer, often a contractor, is brought in late on a project, having to learn the product to be documented as he or she writes. In fact, learning the product to be documented is a routine part of the technical writer's job, but a shortened schedule leaves the document's success entirely to the quick-wittedness of the writer.

Changes

Changes in design or specification during product development may upset the schedule and destabilize the product, product testing, and the technical documentation effort.

Expression

Of course the legions of people attending "Improve your Business Writing" seminars can attest that writing is difficult in and of itself. Technical writing has its own unique difficulty, the difficulty of expressing technical information clearly.

The So-What Factor

Add to this a fifth obstacle: the manager who utters the time-honored motto of technical writing, "Let's not worry too much about the manual-no one is going to read it anyway."

Training the Technical Writer

Maybe the problem is training. What sort of training do technical writers get, and is that training appropriate? Peter Kent, author of Making Money in Technical Writing, says many writers he met while he was starting had been attracted to the field as a temporary job; they were "just passing through."

Today many avenues of instruction are available, including college degrees focused toward the vagaries of communicating technical information. The field is called technical communication, and many modern technical writers prefer to be called technical communicators. This term encompasses the numerous ways in which a person with the title of "writer" contributes to a project, whether as an advocate for the customer, a part-time trainer, cutting and pasting graphics with a page layout program, or supplying text for the label on the outside of the shrink wrap.

For several months I followed a technical writing newsgroup on the Internet. One frequent debate among professional writers was which degrees should be required as an entry to the profession, and whether there should be formal requirements and certifications.

Listening to stories of established writers in the field, it was evident that employers weren't always looking for specific degrees or training. Some employers looked for an English degree, but others looked for technical experience, or a love of technology and the ability to communicate it.

Just Passing Through

Kate Zanello, a contractor working in the Boston area who has written documentation for Scudder Investments and Lucent Technologies, confirmed that many writers she has known just fell into technical writing and did not intend it to be their goal. Kate was testing software in a Quality Assurance department when she was asked to move onto the road as a customer support representative. There she spent some of her time "editing documents and doing curriculum development," she says. When an opening as a technical writer appeared in another part of her company, she accepted.

Kate says she has benefited most by having had "a lot of mentors" and from "peer review, colleagues that helped with ideas of how best to present information."

Learning by Doing

This notion of learning by doing smacks of apprenticeship-a recognized form of teaching and training since at least the time of Michelangelo (okay-so my history is weak and I made that up). And this leads us to another way to get into technical writing: by just being around.

Michael Bremer's book UnTechnical Writing advocates, somewhat unconventionally that writers should try their best to communicate in a way that everyone can understand! Bremer also thinks that "whoever is around" can do a great job, with the right management support, the right tools, and the desire to communicate clearly.

Build Better Manuals

Here's more advice about how to actually improve the manual from http://developer.kde.org/documentation/design/ui/writingmanuals.html. (The attribution is a little fuzzy but the author seems to be Web usability and user interface guru Jakob Neilsen summarizing fellow guru Bruce Tognazzini): Telling users to RTFM (read the ******* manual) doesn't help. Fixing the manual does. Follow these five easy steps:

1. Supply a real manual. A real manual (if you didn't know) is made of dead tree. Electronic documents don't cut it. They aren't physically portable (like a book) and they are difficult to read (lower resolution).
2. Explain the problem being solved. Don't just reformat the design specs and print them. A list of features/functions is just as bad. Humans find it extremely difficult to store free-floating information. Explain a problem and offer a solution and people will remember it forever.
3. Present the concepts, not just the features. Give the user the framework to hang the details on. Any time you learn a new piece of software, you go through the process of constructing a mental model of the software, what Don Norman calls the "User Model." Building a model requires a framework, and the framework consists of these large, key concepts. Without a framework, it is extremely difficult to learn.
4. Give them more than they deserve. Manuals need to cover the task domain, not just the operation of the program. (That doesn't mean that a tax planner manual needs to cover the entirety of tax law.)
5. Make it enjoyable to read. I can't help you there.

Making It Easier

If you are a business that uses technical writers, give them time and bring them into projects intentionally-and early. If you give your employees new technology, give them the manuals, encourage them to use them-and give them time for the learning curve!

Communication is something we talk about all the time, but seldom do we treat it as crucial. So the next time you successfully put together your gas grill or program your cell phone with the aid of detailed diagrams and a ton of technical prose, keep this in mind: It ain't as easy as it looks.

Doug Nickerson has been writing and testing software for ten years and enjoys sharing his experiences through his freelance writing. Doug often contributes reviews to the Electronic Review of Computer Books. He lives on Cape Cod, (Massachusetts) with his wife and two small sons. He can be reached at dougnickerson@yahoo.com. This article first appeared in the Computerbits Magazine and is reprinted with permission.