The Ten Plagues of Technical Communication

This time of year, my family, along with many others, will gather to celebrate the festival of Passover. This holiday, like all Jewish holidays, can be summed up as: "There was a battle, we won, let's eat."

During Passover, we celebrate the liberation of our ancestors from slavery in Egypt. Lest you think slavery is an outdated idea in our so-called modern, free world, simply look at how many people are slaves to their cell phones, Blackberries, to their computers and cars, and to all their other material possessions. The things they own end up owning them. That's why Passover is one of the most popular and well-celebrated holidays, because the concepts of freedom and slavery are still relevant today.

One of the more colourful segments of the Passover story is the ten plagues brought down upon Egypt. Just as freedom and slavery still exist today, so do plagues. The ones faced by technical communicators are not quite as harsh as blood, pests and wild beasts, but can still cause us great pain.

Here, then, are the modern plagues that technical communicators face today:

1. Difficult reviewers - We've all experienced these. Reviewers who don't return drafts, or return them with such helpful comments as 'What?', 'Needs work', 'No!' or my personal favourite 'Huh?' Reviewers like this need to be placed in front of a firing squad for life.

2. Poor documentation software - Although great improvements have been made over the years, the software for creating documentation is still as not as good as it could be. Microsoft Word is the after-thought of a documentation tool. FrameMaker is quite solid, but still has many annoying quirks. In general, there are few tools, if any, that do everything we want at a reasonable price. We've come a long way, baby, but there's still so much further we could go.

3. Developers - Developers are like dentists - they're not really appreciated, they cause us great pain, but we need them. They are technically brilliant, somewhat autistic individuals whose greatest strength and weakness is that they focus on the two M's: mechanics and minutiae. That's why developers usually make bad tech writers. If you've ever had the misfortune of reading something written by developer, you'll know what I mean. It can only be described as "mutant documentation."

The problem is that developers have trouble standing back and seeing the big picture, and that's where we come in. We sift through the details and extract exactly what the end user really needs to know.

Also, some of the most challenging documentation is that aimed at developers - SDKs, APIs, Technical Guides, Data Dictionaries, and so on. Because it can be very dry and tedious to work on these, the pay is often quite good; you just have to be comfortable writing for Martians.

4. Marketers - The creature who is the polar opposite of the technical writer is not the developer, but the Marketer. Technical writers like to use as few words as possible, and ones that are simple and clear, with no fluff. Marketers, by contrast, like to use many words, often long, unclear, fluffy ones, to overwhelm the reader. Marketers love words and phrases such as: synergize, leverage, empower, paradigm, extreme quality, customer-focused, customer-obsessed, customer-driven, and so on, ad infinitum and ad nauseam.

There is marketing writing, and there is technical writing, and never the 'twain shall meet.

5. Billboard designers - Although you could lump these specimens with marketers, they are so particularly evil that they must be singled out. Like user guides, billboards are a form of communication designed to quickly impart information. However, many are so poorly designed, I wonder how their designers make a living. The type is far too small or has such poor contrast that it's almost impossible to read. The sad thing is that companies pay tens of thousands of dollars for this illegible junk.

6. Missing or bad indices - An index is one of the most important elements in any document. Users often turn first to an index to quickly find the information they need, often under stress. A user guide or online help is often only as good as its index. Therefore, good indexing skills are critical. Unfortunately, many writers neglect this important stage. They either fail to include an index, or include a skimpy or confusing one. Put yourself in the reader's place: wouldn't you want to be able to quickly find what you're looking for?

7. Duped docs - Duplicated text is the bane of my existence. I've spent more time trying to merge, conditionalize and normalize duplicate copies and versions of text than I care to remember. In one project, I merged twelve Word installation guides into one single-sourced FrameMaker document. It was pure pain, but it sure looks good on a resume.

8. Bad software - A strange and deadly belief has developed that if the software you're documenting is poorly designed, somehow the documentation will magically fix it. To the deluded who hold this belief, I ask: would you drive a car that had faulty brakes if the user guide warned you they were faulty? Of course not. Still, we don't want the software to be too easy to use, because then users wouldn't need any documentation!

9. Outdated documentation - It's out there, and we've all seen it. The docs that haven't been looked at or reviewed in years, possibly decades. You know it's a bad sign when you have to travel down into the cold, dark, bowels of your building to try to resuscitate old printouts. Here's one segment from an old manual I found: "You can send a one-page fax in as little as 27 minutes!"

10. Ignorant Managers - Many managers have no clue about the complexity and challenges that the documentation department faces. The usual response when presented with requests to improve the documentation quality and processes is "Documentation? Hey, I use Word - don't you guys?" The higher the manager, the greater the ignorance. It's probably because of the neckties they wear - it cuts off the oxygen to their brain.

Conclusion
Every generation and every profession faces its own plagues, and it's true that some plagues are "gentler" than others - managers like to call these plagues "challenges." Challenges are tough but they make us grow. Both Passover and Easter celebrate growth and redemption. Therefore, may we and all our documentation be redeemed this year, and may we all avoid as many of these plagues as possible.