© 2012 by Marv Goldberg

It was a long, long time ago. Volcanoes were still erupting regularly; dinosaurs were still roaming the Earth; computers were still made out of wood. It must have been around 1976. I was a Payroll Manager for a small paper recycling company that had a home-grown payroll system. It failed. Constantly (but not consistently). Every payroll cycle I'd hear a report of the latest disaster to befall our long-suffering workers. Sometimes the system would decide to skip state tax deductions, or double the FICA, or simply refuse to produce checks for an entire plant. We spent a lot of time writing out manual checks (and never did get satisfactory reasons why any of this happened).

One day, I got tired of hearing that "the system had another problem last night". It was time to take these attacks personally. I instructed my payroll clerks to say, from then on, that "Fred was sick again last night". I thought it was cool and they loved it. We would speculate endlessly on the nature of Fred's most recent illness and talk enthusiastically about the need for euthanasia.

But why "Fred"? Alas, I simply can't remember. It just happened to be the name that popped into my mind at that instant. Did I know any Freds? Sure. But I also knew Bobs and Carols and Teds and Alices.

Fast forward to 1982. Different job; different company. I needed to use IBM's Exec 2 utility language for various purposes and spent a lot of time annoying my boss to explain the arcana of its command structure. He kept promising to write a guide for everyone in the data center to use, but could never seem to find the time. Finally, he volunteered me to do it. Not the worst thing in the world; at least I'd learn what I needed to know while I was creating it (read: "while it was destroying me in the process").

Enter (or, more accurately, re-enter) Fred. My Exec 2 manual was liberally sprinkled with examples and they tended to include him. Management blessed the guide and it was disseminated. Once again, Fred was on his way.

A couple of months later, I was approached by our IBM Customer Engineer. He had heard about my Exec 2 guide and asked me for a copy. Now it gets interesting. Within a year, IBM manuals started having examples involving "Fred". Was it my Fred? Did IBM swipe the idea from me? Was it simply Convergence Of Fred (a scientific theory hotly debated in the halls of academe)? Regardless, I was proud. I was on the ground floor of documentation history. (Heck, if IBM was willing to go with Fred, I was surely on the right path!)

In time, Fred came to head up my pantheon of Example Gods. They included Herbie, Irving, Zelda, Sollie (Fred's pet aardvark), and Clarice. Somewhere along the way, Fred even got a last name ("Ebcdic"). Their merry adventures graced the pages of my manuals for years and years.

I miss Fred. I'm not allowed to personalize my writing anymore. Might make it too enjoyable for the reader. It's a shame, really. To begin with, what we write about is intrinsically boring (how many times have you read a chapter on product installation that you "just couldn't put down"?). On top of that, consider the way we're forced to write. My writing is now dull as dishwater (as is yours, and yours, and especially yours). So much for putting customers first. (Do you really believe in your heart that customers clamor for every manual to read exactly like every other one? How absurd. They want intelligently-written, useful, readable manuals, not soporifics stamped out by a cookie-cutter.)

I'm sure there'll come a day when our documentation will have to be issued with the following caveat: "Warning! The Surgeon General has determined that overuse of this documentation can have adverse effects on your health. Narcoleptics and those with a low threshold for pain should avoid the help files altogether. Do not operate heavy machinery while reading this product."

What can you do about it? Rebel, that's what. I don't want your manuals to sound like mine and I hope you feel the same. (I suppose it depends on whether you feel that documentation should be created by people or extruded by robots. Or even, for that matter, read by people or by robots.) Start small. Slip Fred into one of your examples. Do it often enough and sooner or later one will get past the Evil Editing Police. At that point, you're home free. You've created a precedent! Fred can roam, without hindrance, through the verdant landscape of your documents. Herbie can play his roguish pranks on the others. Zelda can lend her panache to your examples. Sollie can romp from one anthill to another.

Don't give up. Don't give in. Make your documentation something a human would want to read. After all, we owe it to our customers.

Unca Marvy's Home Page

More Essays