Re: document structure? minimalist docs?

[Ann Mackenzie <TekDocWis -at- AOL -dot- COM>]

In a message dated 98-07-06 18:51:44 EDT, you write:

> The previous person who did our documents put the manual in the
>  following order, on the grounds that things used most often should be
>  up front in the document: safety notice, reference section, user's
>  guide, installation.

Hi Becca -

In my experience, people often skip over material such as "How to use this
manual" and "Safety instructions" in favor of getting right to the meat of the
manual, which is often Operating instructions.  So, I  try to put chapters in
order by what they will be looking for:  Operating, Maintaining,
Troubleshooting, with an appendix on Installation, if I can get away with it.
Within these sections I sprinkle warnings and cautions wherever the reader
needs to see them.

< <I know that our current documents are inadequate (for example, our
maintenance section says to check the oil every 6 months, but doesn't
say where, what to look for, or how to add new oil... or what kind to
add even.  when I asked, I was told "they'll know, and they'll use
what's on the floor anyway." - erk.) but how much is too much?>>

I try not to ever let engineering & programming tell me "they don't need that
info"  Invariably, the user who is hunting your manual for information on
maintenance *really does* need it.  Users are very often much less
knowledgeable than the experts can imagine.  Its up to us to accurately
provide *all* the info our readers need.

Good luck with your new venture - it sounds like fun.

Annie
==========================
Ann Mackenzie:   AnnMacknz -at- aol -dot- com
TekDoc - Technical Documentation, Inc. in Milwaukee, WI, USA
Specializing in software, engineering, and policies & procedures.