Re: Clarity or Talking Down?

Subject: Re: Clarity or Talking Down?
From: John Engler <jengler -at- SPILLMAN -dot- COM>
Date: Wed, 28 May 1997 10:09:17 -0600

Here's an experience on the subject. We were installing a new piece of
in-house software. The installation department had written a procedure
for setup and use, but one of the upper-managers, a programmer himself,
had a difficult time following and understanding the document. So they
asked me to rewrite the doc. I wrote it just as I would write to my
users--in very simple and clear language, according to what we term "the
lowest common denominator." This manager was pleased with the re-write,
and there have never been any questions about any of the procedures.

Here's another thought. We had several site administrators of our
software in-house, and we asked them (after a lengthy debate among the
writers) to what level we should write or manuals. They *emphatically*
wanted instructions and explanations written to the most basic user.
When we asked if that wouldn't bog down more advanced users, they said
that their advanced users would easily be able to skim until they
reached the information they needed. We've kinda adopted that as our
rule of thumb.

But as always, it comes down to your audience. Good luck, Kevin. And
when you do make your decision, stick by your guns. After all, they
hired you as the *right* person to do the writing!

John Engler
Technical Writer
Spillman Data Systems
Logan, UT

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Re: Java-based help, HTML-based help
Next by Author: on-line help in Java applications
Previous by Thread: Re: Clarity or Talking Down?
Next by Thread: Re: Clarity or Talking Down?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads