Visual Communication and Design, Now with Audio!

This cautionary tale deserves a feature in your new Management Leadership Failures Blog. ;)

I've thought of a few subtler ways a technical writer can screw up. These are things every technical writer needs to understand, because they are in the best position to prevent these kinds of errors:

I left my last contract job (outside Microsoft) after finishing one assignment, and researching the next one they wanted me to do. At first, it sounded like a writing task. But after a while I realized the underlying challenge was organizational. There were large gaps between what the customizer teams wanted and what the development team was willing to commit to. Writing can bring people to the table to tackle differences. But it can't substitute for good engineering, or succeed without political support at the highest necessary level. I couldn't solve those problems, so I made the right decision to step away.

Non-writers often have many ideas how the writing task is accomplished, and what role it plays in the success of their project. Sometimes it's hard to get an expert to participate in the drafting process. But it's a mistake to let experts decline draft reviews. It's also a mistake to fail to respect their time. Failing to respect and build relationships with experts is probably one of the largest errors a technical writer can make. Few writers can get the "last 5%" of the story without the active help of experts.

Taking someone's word as fact can be a major technical writing blunder. At first this might not seem obvious. Most people aren't telling lies at work. But it's remarkable how often small details get fogged up or left out. Verification is my first task. It takes time, especially at first. But oversights and errors consume a lot more time!

One technical writing error I particularly hate is a failure to write to a single audience. Editors can't always sense these errors... the language might flow fine, but the topic itself might be wholly inappropriate. For example, sometimes there are only subtle differences between the software developer and system administrator audiences. And within your audience, are you talking to a beginner, or an expert? Technical writing that blurs these targets might be readable... but it can't be very effective.

T.M.I. (too much information) is a techical writing error I try to avoid. Usually this is resolved by considering the audience. Documenting exceptions can also lead you into this trap. For example, testers like to offer details of how everything can fail. But if the failure isn't plausable or likely, does it really make sense to enumerate each possible failure scenario? Save your readers some frustration, by leaving out the minutae of tangentials. I'd rather emphasize the instructions that *prevent* the failure.

P.S. George Soler steered me here. And I ought to mention that I'm looking for contracts. I know you're looking for FTE's, but let me know if you've got CSG/vendor needs.