TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
always
> prune a tree, growing limbs takes a lot longer.
> Therefore, I cannot even believe that some individuals are arguing that it
is
> preferable to "leave out data" for the consideration of the reader. For
all
> you know that one chunk of information you left out would have made the
> difference between awakening a genius or touching off nuclear war.
<RANT>
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?
</RANT>
John
John Garison
Documentation Manager
Integrated Development Enterprise, Inc.
150 Baker Avenue Extension
Concord MA 01742-2174
