Technical Writer

Let’s face it. Sometimes technical documentation can be downright boring.

Sticking to the facts—just the facts—does tell the reader what they need to know, but do they retain it if it’s presented this way? Not normally.

When information is presented as an impersonal list of facts most people simply turn off. Or they use the material as a lookup for when they want to know a specific detail. When they’re trying to learn something they need more. That’s what makes the Dummies series and other books like them so popular.

I have used the Dummies series myself with varying degrees of success. I know people who love them, and others who hate them.  I’m a big fan of the Head First series myself, and they invoke a similar range of reactions.

When I want to get a message across I try to use graphics where I can. At work I occasionally use cartoons to get my message across. I can’t draw, otherwise I would use them a lot more. Or I will start with a graphic, say a screen dump, and add notes to the graphic so that the user has to read the notes on the graphic.

Both of these are more effective at teaching new users than step-by-step instructions.

The modern trend is for graphics and video to demonstrate new concepts. It’s being done less and less with words now, but it can still work if it’s done properly.

Designing an Authentication System: a Dialogue in Four Scenes was written by Bill Bryant back 1988 to explain how the Kerberos token ring system worked. It was updated in 1997 by Theodore Ts’o. For a document that’s 20 years old—and that’s ancient in IT terms—it does a pretty good job of explaining a complex technical subject.

Last Modified : March 24th, 2008
Filed under : Tech Writer
Navigate : Previous post / Next post