Friday, August 10, 2007

Should Tech Writers be Writers?

In a response to a post on Tom Johnson’s excellent I'd Rather Be Writing blog, reader Kim Nathans posted this

I also came across a study on learning using a 94-page manual versus using 25 flash cards. It turns out that people learned more quickly with the flash cards covering key ideas and hints, and no step-by-step instruction.

How depressing! I was hired as a “tech writer”(emphasis is mine – AJP) but it turns out that users only want a pile of screen shots! I have to rethink all of this before I tackle this next documentation project. *sigh*

I can sympathize with Kim’s point, back in the mists of time when I first joined a technical publications department after graduating college it was because I wanted a career where I could blend my engineering degree with my love of the written word. Since the age of seven I always wanted to be a writer, but my natural tendency towards the mechanical drove my education path in another direction.

In the twenty plus years since as a tech author, editor, heading publications shops, consultant and working for software vendors selling into the tech pubs market I’ve always heard the same story – heck I even heard it this week. “Why don’t people respect technical publications?”

Maybe part of the problem is that the vast majority of us are Writers. We love the written word. Maybe we love it a little too much?

We need to ask ourselves is the written word the best thing for Technical Publications?

Perhaps the reason we don’t get the respect we feel we deserve is that what we produce on the whole is not doing its job as well as it should?

On the wall of my home office is a certificate I was issued with by the Technical Publications industry organization, the STC, many years ago. I’ve been a member of the ISTC and STC for most of my time in this industry, Take a look at the name of our industry group. The STC – The Society for Technical Communication – its not the STW. That last word is important. We are Communicators.

The old adage that "a picture is worth a thousand words" has resonance for a reason.

Two of the most successful tech doc projects I ever worked on were driven by graphics. One was a touch screen graphical navigation system for mechanics maintaining underground trains. They navigated to the area of the problem by literally touching on pictures of the area of the train with the problem. The other was a entirely pictorial breakdown procedure for a boat manufacturer, the only text was the part numbers.

If anyone has seen me run a training course, I no longer use a training manual. I use screen shots, practical demos and a white board. I draw and I talk.

Several years back I wrote a white paper on using graphics as a “universal language” in technical communication. Over the course of the next few years I was asked to present that paper over and over again, it even won a couple of awards. No other paper I have ever written on any aspect of technical documentation has drawn (no pun intended) that sort of response.

Examples of effective communication using more graphics than words are all around us. I spent several years in the aerospace industry, and what’s the most effective and widely viewed piece of documentation in that industry? The safety card placed in every seat back pocket. Next time you fly, pull it out and take a look at it. It communicates across language barriers by use of simple clear illustrations and internationally understood symbols. It’s easy to look at, and you can assimilate the messages and procedures at a glance.

Just one more example, the biggest lesson I ever learned about communicating was spending a day listening to graphics design guru Edward Tufte , if you can, go listen to him talk.

Another great resource on communicating with words and pictures is Scott McLoud’s, Understanding Comics. Yes comics – think about it man has been combining words and pictures to tell stories and pass on information for centuries.

Before any one thinks I’m anti-writer, I’m not. When people ask me what I do, I tell them I’m a Writer. I write books, magazine articles, blogs, websites – and yes, comic books.

I’m proud to be a writer. But I leave being a pure writer to the evenings and weekends. When I’m in the office I try to be a Communicator, and use whatever techniques that work best for my “end user.”

I still use words, but I also try to use graphics, video, animation, audio and anything else, including flash cards, that will do the job of communicating in the most effective manner.


kim nathans said...

You make a good point. Although my title is "writer," my job is to ease the user's experience and to uncomplicate complicated processes. If pictures do a better job than words, then pictures it must be! I should have known that, but somehow felt that relying on images was "cheating

My previous job involved writing for developers, and the Help2 files I created could seriously slow down the opening of Visual Studio.NET. I guess I got too invested in the screenshot stinginess that we had to adopt in order to avoid a negative user impact.

Now I write for end users, and I knew it would be a different experience. I was worried about voice and language and number of steps in a procedure, so the graphics issue took me completely by surprise. I was disappointed that I didn't get the feedback on my first project here in time to change my tactics, but I'll catch that one in the next maintenance pass, and be more generous with graphics in my second project here.

So in answer to the question in your title, well, we should have the abilities of writers, but consider ourselves communicators. Thanks for the reality check!

Tom Johnson said...

Alan, I think I should have left a comment on this post a long time ago but didn't. I was just reviewing the importance of screenshots, and I reread your post. I couldn't agree with you more. We underestimate the importance of the visual in our documentation because we often think of ourselves as "writers" more than "communicators."

Good images and graphics take time. It's more than simply adding a screenshot here and there to accompany documentation. Thanks again for the post.

Alan J. Porter said...

Hi Tom - Thanks for the feedback. I've been talking to Scott Abel about hopefully doing a presentation on this very subject at DocTrain East in October. If I get a confirmed slot I'd love to talk to you some more and get your input.