10 pet peeves of technical writing

by Tom Johnson on Jan 27, 2007
categories: technical-writing

Holly Harkness's recent post on 10 rules of technical writing got me thinking about the 10 pet peeves in technical writing that drive me crazy. Here they are:

Pet Peeve #1. Instructions that aren't modular.

I wish I had a better adjective for this, but do you ever find that instructions you are trying to follow require some unmentioned starting point that you can't get to because the instructions assume you were following along chronologically in their manual or help file, but really you keyword searched your way to your location? I absolutely hate this. It makes me want to squeeze the writer's neck!

Pet Peeve #2. Instructions that aren't task-based.

I almost always want to do something, right away. I once began reading the AuthorIT manual and found that even up to page 87, I still hadn't come across a task. It was all introductory, explanatory fluff — this button does this, this is this screen, this is the so and so forth module, etc. I read "to do."

Pet Peeve #3. Instructions that are inaccurate.

Nothing is worse than realizing half way through some task that step 4 (for example) is impossible to complete because the button or menu simply does not exist. Do you realize how frequently this occurs in technical documentation? I once served as our team editor and would try out instructions. At least a quarter of the time the instructions were wrong — the writer omitted a step, called something by the wrong name, or the interface had changed, etc. Truly frustrating for the user.

Pet Peeve #4. Steps that confuse bullets for numbered lists and vice versa.

It's really the mark of a beginner when you see a list of steps the user is to perform in sequence, but the steps are written as bullets. Or when there is no specific sequence, yet the list is written with numbered steps. This seems like tech writing 101, so when I see the writer has gotten it wrong, I lose faith in the instructions immediately.

Pet Peeve #5. Instructions that have unnecessary screenshots, and instructions that are missing necessary screenshots.

I know this seems a bit of a contradiction, but the writer ought to know when a screenshot is needed and when one isn't. If the step is confusing, add a screenshot. If it's a no-brainer, leave it out. If you have a task that is only about 7 steps long, but the writer has included a screenshot every step of the way, it bloats the task and makes it look more arduous than it is. But sometimes every word in the world can't describe the information conveyed in one screenshot.

Pet Peeve #6. Writing that lacks organization.

The table of contents (TOC) should present a logical order to the material, and when you can't get a feel for the topic from the TOC, or and the general way it's organized just seems unclear, it bugs me. Organization is probably the hardest part of technical writing — getting the organization right, that is. Organization is the way you shape content into a logical, task-based form that the user looks at and immediately follows. Organization is the way you bring order to chaos.

Pet Peeve #7. Writing that is longer than it needs to be.

Ever read a paragraph and think everything could have been reduced to one quick phrase, or even deleted entirely? It drives me mad when I sense writing to be unnecessarily prolix. To think that I've wasted my time reading fluff and filler when the writer could have gotten down to business and delivered the meat straightwith — my blood starts bubbling.

Pet Peeve #8. Instructions that assume the user is a programmer.

If you're writing instructions for programmers, that's one thing. But do you ever find yourself reading something and saying, geez, what kind of technical knowledge is required here? Couldn't they have dumbed it down a notch or two (or five)? I felt this way one time when trying to install Movable Type on my own host. Suddenly I had to be familiar with Perl scripts, and if I wasn't, well then I should be paying someone else to install it. Always assume your reader knows less than you think.

Pet Peeve #9. Online help that you can't print.

Have you ever been surfing around in RoboHelp's online help and suddenly thought, hey, it would be nice to print all of this into a manual. Maybe not the entire manual, because that might be 400 pages, but at least all the topics in the section I'm reading? Yet some instructions exist only online, in little chunks, with interrelated tasks always separate from each other. You have to click your brains out following link to link to try to navigate. Sometimes you need to print because you must follow the steps one by one and can't always be maximizing and minimizing windows.

Pet Peeve #10. Irrelevant project meetings that waste the writer's valuable time.

Okay, so this pet peeve isn't really one that involves writing, but it certainly involves much of the life of the technical writer: sitting endlessly in project meetings listening to developers and project managers and testers yak and yak and yak about server load and databases and this and that, never acknowledging or mentioning anything related to documentation. After an hour the meeting ends and you as the tech writer feel like you just wasted your time. I now bring ample reading material to most meetings. This can change the meeting into a more enjoyable experience.

What are your pet peeves?