Written by Mark L. Levinson

I suppose it’s unusual for a technical-writing department to have a slogan, but when I worked at Daisy Systems the department had a slogan:  “The user is the hero.” 

The slogan was there to remind us that the user manual is not about how peachy the product is.  The user manual is about how admirably and efficiently the user, aided by the product, can accomplish the tasks at hand.  If the product, as presented by the manual, makes the users feel good about themselves, then the users need no convincing that the product is a good product.  They’ll love the product without being told to.

But as Hemingway said, “If you tell it, you’ve lost it.”  Suppose you write, “Wasn’t that easy?  Wasn’t that fun?  And now, thanks to the TiePlumb computer-based photographic gauge for necktie straightness, your bowtie is perfectly horizontal and you’re ready for that crucial business meeting.”  By characterizing the experience to the user, you’ve robbed the user of the opportunity to be the discoverer, and thus the owner, of the experience.  The hero.

Everyone has been a hero at work from time to time because of owning some useful knowledge — what the items on the salary slip mean, how to find Outlook’s temporary files, how to unjam the printer before the secretary can read what’s jammed in it.  It’s a good feeling to be in command of knowledge that you’ve discovered.  And that’s the feeling that we want to give our readers.  One way to intensify that feeling, but a risky way, is to cut back on explanations so that the user learns from moderate independent effort backed by minimal documentation.

We all know people — some of them in our mirrors, I’m sure — who would rather fool around with the menus of a software product than read the manual.  This is because they want to create their own experience and to feel that they own their own knowledge.  Educators tell us that people in fact learn better this way; the downside is that they may happen to learn an awkward or even incorrect method of doing things, take a long time to learn it, or not manage to learn at all.

Back in the early 1980s, I began every software user manual with an explanation of how to use the mouse.  If you think it’s instinctively intuitive that forward movement of a mouse corresponds to upward movement on a screen somewhere to the left of it, then you’re either young or forgetful.  And the thing looks no more like a mouse than Mickey Mouse does.  Okay, a little more.

But today, of course, we take mouse mastery for granted.  How much more can we take for granted?  Can we skip the documentation of an “Are you sure” message?  A cancel button?  A whole toolbar of geometric shapes?  You need to know your reader’s expectations, and how well the product meets those expectations, before you can know how much minimalism is safe.

What if a feature is generally easy to understand but occasionally deceptive?  Suppose that you can freely save and delete pictures of any necktie, but when you delete the last picture of a given necktie, you delete its whole history and description from the database and there’s no warning.  That’s a problem with the product’s interface, but as the saying goes, when the product is a dog, the documentation barks.  You may have to strew the whole document with repetitive warnings.

After all, the experience should be the user’s to create and own, but it had better be a good one.

Comments and questions are welcome:

All Why of Style Articles

Do you know about the discounts for Israeli tech writers?