Re: Clarity or Talking Down?

[John Engler <jengler -at- SPILLMAN -dot- COM>]

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
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html