10 pet peeves of technical writing
January 27th, 2007 | Posted in blog 13 Comments »
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?
Sponsors
Tags: Technical Writing
If you liked this post, keep updated with new content: Subscribe to I'd Rather Be Writing.
Both comments and pings are currently closed.
0 Subscribers
Mark Baker (7)
Greg DeVore (4)
Jonatan Lundin (4)
bg (3)
Jim Reardan (2)
Marcia Johnston (2)
mma (2)
Tammy P (2)
A Andrew (1)
Aldergrove drivin... (1)
I find the fact that these two were chosen the most often very interesting as they represent almost polar opposites in terms of delivery style. Tom’s posts have a much more personal tone and are oftenentirely based on his opinionwhere Scott’s are much less about his opinion and more like reading a news-oriented post or press release. The remaining blogs listed for this question were chosen in the following order from most read to least read:
Tom,
I couldn’t agree more with many of your observations but I personally believe that many of the items you listed are a direct result of the writer being constrained by one or more of the following:
limitations resulting from the choice of a particular tool (which is often outside the control of the writer)
a lack of sufficient time or assistance to address loose ends
an organization that demonstrates by its actions that documentation is not high on its list of priorities
Any one of these could create the type of issues you mentioned and any combination would almost guarantee it. I am the type of individual who prefers to look to the root cause of a particular issue with an eye toward resolving it, if possible. The problem with these issues is that they ultimately create feelings in the writer that he or she is not appreciated. While some of the items on your list could only represent carelessness or blatant apathy on the part of the writer, I have to wonder how many of those writers might be more careful or more caring about their work if they felt truly appreciated by their respective employers.
Don’t misunderstand me. I’m not saying that all the problems are a result of things outside the writer’s control. I firmly believe that we still have a responsibility to ourselves, if nothing else, to represent ourselves and our profession as positively as possible by doing everything we can to improve whatever we touch regardless of the limitations. If a writer has lost the desire to at least attempt to improve his or her work, perhaps its time to seek some other form of employment.
Tom,
I agree with most of your pet peeves. I haven’t had to do complex online help in about 5 years, so I’m not sure how much of what you describe is an inherent limitation of the tools available and what is poorly implemented by people using those tools.
I’m with you on #4. Huge red flag. I’m afraid I’ve been guilty of #3 somewhat too much lately. Too much to do, too much to do. Luckily I have a large group of patient testers so we catch most mistakes before things are posted. The slightest version changes cause all sorts of problems though. I guess I’ll have to list that as a peeve–differences between platforms and versions.
MY biggest pet peeve is when the topic turns to the documentation, but the folks in the meeting for some reason think they need to start explaining screen captures or basic documentation procedures to me. Really. They truly believe that I’m terribly competent, so I’m not real clear on why this happens.
I’m glad to have found your site.
Clyde,
I agree that technical writers must feel appreciated and take pride in their work to avoid the pet peeves I listed above. When writers stop caring about their work, the quality of their documentation certainly drops.
Writingweb,
Thanks for your comments. I think it’s great that you have a large group of patient testers. Accuracy is probably more important than anything else.
Wow, if someone started explaining screen captures to me and other documentation-related basics, I would have to add that as pet peeve #1.
[...] “>10 pet peeves of technical writing Holly Harkness#8217s 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#8217t modular. I wish I had a better adjective for this, but do you ever find that instructions …pet:2 writing:2Source page [...]
Your team has meetings?
I know I missed the boat that was this conversation, but I only discovered the site today. I was looking for information on when to use screen shots. So in regards to Peeve #5:
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.
I thought I was doing great with my screen shots, only providing them when their use would save me several dozen words. My boss was happy that we could cut down on maintenance costs because the screen shots are so quickly outdated by the addition of new features.
But then I got my first actual feedback from a new employee (Director of Development) and he was disappointed that I didn’t include a pictorial storyboard of the process flow. It turns out that he didn’t so much read any of my documentation as just glance at it. I started thinking about how many of the consumers of this documentation will be like him, and was depressed to realize that there will probably be a lot more like him than like me (a compulsive reader who will read every word in front of her face).
I’ve been googling (too much today) and have found that there are two sides to the “Screen Shot or Not” issue.
Tech writers (and their bosses) think that less is more.
Users think that more is more.
I asked a marketing intern in our office for his opinion, and he pulled out a very dog-eared and obviously well-used document that he had printed out. It was nearly all screen shots with certain UI items circled sloppily (like they’d used a mouse to do it freehand). He enthused for a couple of minutes about this being the most useful piece of documentation he’s ever had, because he can quickly refer to it and easily find the steps he needs to take to accomplish whatever task it conveyed.
I also came across a study on learning using a 94-page manual versus using 25 flash cards. It turns out that people learned more quickly with the flash cards covering key ideas and hints, and no step-by-step instruction.
How depressing! I was hired as a “tech writer” but it turns out that users only want a pile of screen shots! I have to rethink all of this before I tackle this next documentation project. *sigh*
[...] Nathans left a really intriguing comment on a previous post. She writes, I thought I was doing great with my screen shots, only providing them when their use [...]
Pet Peeve #5. Instructions that have unnecessary screenshots, and instructions that are missing necessary screenshots.
A comment about this pet peeve: screenshots are much more difficult to localise into multiple languages, especially over several software versions. Of course, I will include a screenshot, or part of a screenshot, if required.
A couple of my current pet peeves (no particular order):
- terminology inconsistency, both within the program and within the documentation
- writing and editing without considering the associated translation issues and costs
[...] Nathans left a really persuasive comment on a previous post. She [...]
Hi Guys,
This conversation about pet peeve #5 brought me here, as I am working out a screenshot strategy that I hope will work.
However, my biggest pet peeve is not on the list.
Pet Peeve #11
Writer´s role, project manager´s role, and everybody else´s roles are confused.
I have worked on a few projects for my current client, and everybody´s roles are confused. One day my boss said to me, “you must be more proactive,” even though the subject in question was formally out of my jurisdiction.
Pet Peeve #12
Client incompetence
As a tech writer in a really big company, I am exposed to all kinds of incompetence. It is everywhere, and even though most people don´t see it, the Tech Writer always sees it!
Whenever i got error mail from ezine after submitting my article written by my content writer, i want to discuss the issues or mistakes which goes against the rules or policies of ezine but my writer is so emotional and aggressive that he starting arguing and never understand these pet peeves of content writing.