Re: document structure? minimalist docs?

Subject: Re: document structure? minimalist docs?
From: Sharon Burton <sharonburton -at- EMAIL -dot- MSN -dot- COM>
Date: Wed, 8 Jul 1998 16:38:38 -0700

Every client I have had has told me when asked, that users are "just like
us. They know the same stuff we know." And without exception, if they
actually do a survey and meet their customer base and talk to them, they
discover that the users are everything in the world, but never "just like
us." It actually cracks me up when clients say that now. I just laugh.

You have to balance what the experts say the user will know with what seems
really useful to document. If they know how to change the oil, they will
skip over the part about how to do it. If they don't know, however, they
will get really frustrated really fast.

sharon

Sharon Burton
Anthrobytes Consulting
Home of RoboNEWS(tm), the award-winning unofficial RoboHELP Newsletter
www.anthrobytes.com
anthrobytes -at- anthrobytes -dot- com


-----Original Message-----
From: Ann Mackenzie <TekDocWis -at- AOL -dot- COM>
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU <TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU>
Date: Wednesday, 08 July, 1998 3:49 PM
Subject: Re: document structure? minimalist docs?


>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.
>
>
>




Previous by Author: Re: Important News for Writers (long)
Next by Author: Job posting
Previous by Thread: Re: document structure? minimalist docs?
Next by Thread: Re: Tech writing & incompetence: I am scum


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


Sponsored Ads