The Confabulator Cafe

Tag: technical writing

  • 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.)

  • There is always a Story.

    Sometimes it’s not a very interesting story. Sometimes it hides itself from you, and sometimes it’s so buried in the weeds of poorly conceived presupposition that you have to get out a metaphorical brush hog to make any sense of it all. But you can take it on faith that there is always a Story.

    I’m a technical writer by trade. You would think the craft of technical writing is all about— well— technique. Marching one word in front of the other from the start to the finish, and making sure they all line up in the correct order. Choosing vocabulary and policing acronyms. Herding commas, nurturing semicolons, recapturing run-on sentences. Describing things. Mundane, boring, everyday things that require procedures and user manuals and progress reports. It’s not literature, or even journalism. I have built a career out of writing the kinds of books that nobody in their right mind will ever want to read [0].

    But there is always a Story.

    (more…)