The Technical Writer Lens

Wednesday, April 2nd, 2008 | Technical Communication, Writing Theory & Practice

In a previous post, I wrote about the irony of technical writers not following directions. It made me think about the expectations I bring to online help or a set of printed instructions written by someone else. I think that because of their profession, technical communicators approach documentation differently than users in other fields.

Personally, I come to others’ documentation with a set of expectations. I’m critical at the same time that I’m sympathetic.

Because I create online help content, I have found that I am likely to check a software application’s help system before I go anywhere else for information. Somebody took the time to create it, and I expect that it will answer my questions or tell me how to accomplish the task I’m working on. I understand that there are constraints and challenges in this line of work, so I sympathize with the nameless, faceless writer.

But I want completeness of information. I want the answers to be at the other end of a quick text search. I want the help to tell me how to do something, not just that I “can” do something (in other words, the software has the capability to do something). Picture this interaction:

Ben: I want to get these bulleted lists to use a different image, but it’s not apparent how to do that. Let’s check the help.

Help: Welcome to WordProcessor Pro Plus Help. Enter a search term.

Ben: Bulleted list image.

Help: Your search returned 10,532 results. I’m showing you every conceivable, though sometimes vague, reference to any one of those terms you entered.

Ben: Gee, thanks. They don’t call you “help” for nothing, do they? Let’s try this topic: “List styles.”

Help: With the Styles panel, you can change the bullet image for bulleted lists.

Ben: I can, can I?

Help: Sure you can. I said so.

Ben: No, I can’t. I don’t know how. That’s why I came to you in the first place. But there’s no link to topics with detail about changing the image, and there aren’t any other search results that say anything about bullet images!

Help: No dice, bub.

Ben: You’re kidding. Some help system!

Ben’s wife: You’re talking to the computer again. Did you take your medication?

I have the same expectation as everyone else: Help should be helpful.

One of the technical writer’s axioms is to avoid taking knowledge for granted. Something that’s simple for an everyday computer user or someone who is extremely familiar with power tools may not be intuitive for others. When I’m assembling a set of shelves, the writer of the instructions, as well as the graphic artist if different than the writer, should not assume that I’m the sharpest pencil in the box. Rather, they should assume that I’m the dullest of the bunch—but without talking to me like that’s what I am.

I design and edit the content in addition to writing it, so while I am using someone else’s documentation, part of my consciousness is analyzing the effectiveness of the presentation and whether there are copyediting mistakes. Part of me demands perfection, but the other part empathizes because I have had the experience of going through a document with a fine-toothed comb, only to open a copy right after the printing and see an error staring me in the face. Sometimes, there’s no comb fine-toothed enough, apparently.

My point is that I hold other technical writers to the standards to which I hold myself, which is why I am critical and sympathetic at the same time. I do not always reach the standards I have set for myself, so how can I blame anyone else for not doing it? I know the challenges. I’m familiar with the roadblocks.

The bottom line is that using someone’s documentation should enable me to get the job done. And a bonus comes if I can learn ways to improve my own work by studying that documentation. A critical eye doesn’t have to be just critical; it can be the medium for internalization and improvement.

Share This