Complicated + Ugly = Wrong.

I’m a technical writer. I get assignments, with requirements and (horrors!) deadlines. The content and general format are usually specified. But the way I present the information is up to me.

There’s a rule of thumb in computer programming. If an algorithm is complicated and ugly, it’s wrong. The same rule applies to technical writing. If what you are writing makes no sense, then you need to simplify. Hard concepts require short choppy sentences. Don’t worry about style. Worry about communicating.

Recently I was asked to help update a program manual. The previous version was, in a word, awful. The original author wrote it ten years ago, and he was good at writing regulations— which showed in spades. This book could be prescribed as a cure for insomnia, except we were worried about side effects. The whole project got dumped on my desk with the terse order, “Make it better.”
That manual was complicated. It was ugly. It was oh, so wrong, on so, so many levels.

So I simplified it. I reorganized it into three sections; one for program participants, one for their technical experts, and one for their lawyers. I translated the language from Government-ese to English, added color, “chunked” the information by employing sidebars and call-outs, and modernized the typography and layout. I alternated blocks of technical information with narrative case studies and success stories and added so many graphics the darned thing almost reads like a comic book. I excised the former subtext of regulatory doom and gloom and replaced it with a pep talk. I prepared to defend to the death my decision to use the second person, “you,” when referring to the reader rather than the bureaucratic and distant word “party.”

Then I printed it out, lovingly swaddled it in my best binder clip, and sent it out to the higher-ups for their review and criticism. Sometimes you just have to let your babies go out into the world and face the slings and arrows.

My bosses loved it. (Except for that one typo I missed.) It has all the required program and regulatory information, but unlike the previous version it is readable. Helpful. Simple. Elegant. And right.

(By the way, this is the fourth draft of this blog entry. I started the first three with what I thought was a perfect beginning, after which things got very complicated and very ugly very fast. My “perfect beginning” turned out to be perfectly wrong.)