Friday, October 15, 2010

Picasso, Magicians, and I.T. Technical Writing

Ever wonder how magicians learn their tricks? You gotta figure that these guys (they are after all mostly men) are pretty secret about their, well.. secrets. Ironically, most magicians will share anything they know with you so long as you can demonstrate that you have the skill to pull it off. No professional magician wants to see his "art" messed up by a rank amateur. So most budding prestidigitators start by hitting the books to gain the skills they need to wriggle their way into a "session."

A young lad might find in the local library (you do remember libraries, right?) copies of "The Card Magic of Le Paul", "Close-Up Card Magic", "Reputation Makers", and "The Amateur Magician's Handbook." These and countless others are the foundations of knowledge that can advance the aspirations of anyone looking to join the Society of American Magicians or the International Brotherhood of Magicians (IBM - I can’t make this stuff up!).

But!! You have to be able to translate utter gibberish more or less conforming to the rules of grammar, punctuation and style loosely attributed to English into physical movements so subtle as to be innocuous to the human mind.

Magicians are a verbose bunch - they love to practice, patter, and perform. They are however, lousy technical writers. It is in this regard that magicians, sleight of hand artists, illusionists, escape artists, mind readers - - the whole gabby lot of them - just like I.T. folks.

Just try to learn a one handed shuffle from a written description using only text. It is abusive. I still have knuckles and joints that ache from trying to accomplish the impossible - only to discover that it was, in fact, impossible.

Technical manuals... have you ever read one? Ever tried to assemble lawn furniture from Sears? While the First Amendment to the US Constitution guarantees our right to peaceably assemble, I have yet to ever assemble anything from Ikea peaceably.

Which brings me to my point. Technical writing is hard. Writing a good technical manual requires a specialized skill which can only be observed by watching English Majors who have been threatened in passive voice.

This problem is exacerbated by the delusion that the poison of illiteracy that infects the world’s conclave of technical writers has gently passed each of us by. We are immune. After all, everything we write is plainly clear to child of three, a blind squirrel, a lost lamb, and our mom. Problem is folks, all of Picasso’s paintings made complete sense.... to Picasso.

Simply put, you cannot judge the clarity of your own writing.

Truth be told - your technical writing skills are probably only usable within a narrow context. And by context, I mean to the very few people with whom you directly interact every day. Take one step away from them and your written words might as well be preceded by "Made in Taiwan."

For instance, here is an example of an instruction seen in an airline lavatory. It probably made complete sense to the author at the time of writing, but requires clairvoyance to decipher:

Please do not throw foreign objects into flushing toilet.

Is it the throwing motion that is prohibited here, or is it OK to throw things, so long as the object is of domestic origin? Can I gently drop anything in so long as the commode is not actively flushing? Every word that is added to the instruction actually reduces clarity. You *probably* get the intended meaning; but it... is... not... clear!

The vast majority of emails I read are insanely ambiguous. Authors assume their readers have all of the necessary context and thusly just start their written Rorschach Test. I once received an email that contained nothing but, "Can I get an up or down answer?" I replied, "Probably."  It seemed fair.

If it is your task to create / edit technical information, e.g. how to install software, or a preferred architecture - don’t do it alone. You must take your written result and share it for criticism with members of your intended audience. Have your work reviewed by someone outside of your discipline. You will hate the process, but your readers will love the result.

No comments:

Post a Comment

Follow by Email