Re: Organizing advice needed

Subject: Re: Organizing advice needed
From: Janet Valade <janetv -at- SYSTECH -dot- COM>
Date: Tue, 20 Apr 1999 08:32:53 -0700

<I recently took on a mammoth project. I'm writing a user guide for
a
> 3-year old in-house program for which NO documentation (except some
> pretty minimal online help) has ever existed. No formal training has
> existed either. The program is really massive>
>
I had a very similar contract a couple years ago. My approach was to
document the software use empirically. I sat and watched people work, asked
questions, taped their explanations, until I understood what they did all
day and exactly how they used the software. I spent time with each type of
user who used it--sales, shipping, inventory, accounts receivable, etc. Then
I organized the manual based on the things people did with it. For instance,
a chapter called sales with procedures like entering a new order, adding to
an existing order, modifying an order, cancelling an order, verifying an
order, checking the status of an order, etc. When I was writing the
procedure details, I had access to the software. I also did an introductory
section for each chapter, describing the work flow, with a flow chart. A few
things, mainly queries and reports, were used in more than one context. I
repeated the info, rather than cross reference, because the procedure was
used by different people when in different contexts. If there was a lot of
this, you might make a different decision.

I would be concerned about having to document every screen. I found
that only about 1/3 of the screens were actually used. I didn't document the
screens that weren't used. I passed my findings on to IS, who were happy to
learn which screens weren't used so they could remove them. Perhaps if you
did a chapter called "other functions" and put the unused stuff in there,
someone would see the nonsense in doucmenting every screen. Perhaps your
software is better designed and doesn't have any unused functions.

You need support for this, of course. When you sit with people, you
slow them down and annoy them. I was hired by the IS manager and he
recognized the importance of my gathering info. He did the negotiation for
the staff time that I needed. Your part is to be as charming as possible, as
unobtrusive as possible, as helpful as possible (can I stuff these
envenlopes for you while I sit here?), and bring cookies.

I had fun. I learned a business that was totally new to me
(agribusiness). I did things I normally don't do, such as sitting in a
warehouse all day (maintained at 32 degrees) watching trucks be loaded or in
the yard at the scales watching incoming shipments be unloaded. I now know
how lettuce gets from the fields in El Centro into those bags of salad in
the grocery store. How can you beat that?

Janet

Janet Valade
Technical Writer
Systech Corp, San Diego, CA
mailto:janetv -at- systech -dot- com


From ??? -at- ??? Sun Jan 00 00:00:00 0000=



Previous by Author: Re: Need working-at-home advice
Next by Author: Adobe Acrobat version 4 question
Previous by Thread: Re: Organizing advice needed
Next by Thread: The BEST Things About Contracting


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


Sponsored Ads