Re: Grimoires and Magic

["Marie C. Paretti" <mparetti -at- RRINC -dot- COM>]

At 06:15 PM 1/14/98 -0500, Suzy Davis <andavis -at- AU1 -dot- IBM -dot- COM> wrote:

>I don't think that users necessarily need to know what the designer was=
> trying
>to acheive because it is often irrelevant to the user of the system.

That, I think, is the catch -- what is relevant to helping people do their
jobs as effeciently, and perhaps even as enjoyably, as possible.  It
becomes tricky, though, when writing for multiple audiences.   Case in
point: I am working on a User's Guide for data entry software that follows
an OCR process -- the OCR app "reads" data off forms, but it's not always
accurate, so key entry operators fix the errors.

Now, those key entry operators just need to know how to type data and what
all the stuff on the screen in front of them means.  They don't care how
the data entry app decides what characters need to be fixed, how the thing
sorts data, etc.  They look at images on the screen and type.

On the other hand, their supervisors need some understanding of how the app
works so that they can train their keyers for maximum efficiency -- how do
they process the highest number of forms per hour.  That info varies from
system to system, and to make the decision or know what to vary, the
supervisors need to understand something about the app.

To add yet another level, the system administrators need to know even more
about how the thing works because they are concerned with the overall
accuracy -- getting lots of forms through is great, but not if too much of
the data is wrong.  So they need more detail on how the app decides what to
rekey and what to keep, and what parameters they can set to change that.

One obvious answer would be different manuals for different users.  But,
this particular app is one piece of a larger system that can have 6-12
different stages depending on the customer's needs.  Creating three manuals
for each app would be manual overload, and because not every customer buys
every app, creating three overall levels of manuaols (data entry,
supervisors, system admins) wouldn't work either because the manuals would
either be unwieldy or contain way too much info.

The best I can do is write a single manual for each app and divide it into
chapters based on the different user needs.  In the above ex, for example,
there's a chapter called Understanding Widget and another called Using
Widget.  I expect different people to read/make use of each one.  Or more
accurately, since we send one set of hard-copy manuals with each system and
one set of PDFs, I expect managers and supervisors to read through
everything and print out or copy the relevant sections for various other
folks -- effectively using our manuals to make their own and keeping the
"master set" around for tech support and sys admins.

Constructing manuals means, for me, deciding what's relevant for whom, then
organizing the manuals so that individuals can find all (or most) of the
info they need in one place without having to read five different sections.

FWIW,
Marie

Marie C. Paretti
Recognition Research, Inc. (RRI)
1750 Pratt Drive, Suite 2000
Blacksburg, VA 24060
mparetti -at- rrinc -dot- com
http://www.rrinc.com