RE: Tracking off

Subject: RE: Tracking off
From: John Garison <jgarison -at- ide -dot- com>
To: "'Andrew Plato'" <intrepid_es -at- yahoo -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 15 Dec 1999 10:57:59 -0500


Normally I read your missives with a wry smile - and tend to agree more
often than not. We iconoclasts have to stick together!

But this time I have to disagree. You state:

> Furthermore, nobody is improperly served with too much information. It is
> ALWAYS preferable to "over explain" then to "under explain" You can
> prune a tree, growing limbs takes a lot longer.

> Therefore, I cannot even believe that some individuals are arguing that it
> preferable to "leave out data" for the consideration of the reader. For
> you know that one chunk of information you left out would have made the
> difference between awakening a genius or touching off nuclear war.


After suffering through the Great Peanut Butter Debate of 1999, one of my
conclusions is that you CAN over-document - telling people a great deal of
extraneous information gets in the way of the real information that people
need. Warning people not to open a jelly jar upside down indicates to your
audience that you think they are idiots. Too much condescending information
is annoying and will alienate your readers. Do you still tell them to "Press
Enter" after every command?

In some cases, we writers spend WAY too much time explaining the obvious
instead of explaining the things people need to know but cannot discern from
a UI. What people really want to know is not HOW to do something necessarily
(a good UI will handle many of those issues), bur WHY they should care and
what goes on with what they do. I make sure to let my readers know the
answers to these types of questions: What happens to the information I
enter? Where does it appear later on? What effect does it have on other
information I feed into the system? Why do I need to know about this
feature? What is the benefit of using this function?



John Garison
Documentation Manager
Integrated Development Enterprise, Inc.
150 Baker Avenue Extension
Concord MA 01742-2174

978.402.2907 Voice (new!)
978.318.9376 Fax

Previous by Author: RE: Where do 'old' techwriters go to die?
Next by Author: RE: Baseline Skillset for Technical Writers?
Previous by Thread: tracking off
Next by Thread: Re: Tracking Off

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

Sponsored Ads

Sponsored Ads