Preferred types of software manuals (was: Re: to dialog or not to dialog)

[David Jones/KSBEISD <David_Jones/KSBEISD -dot- KSBEISD -at- DATAHUB -dot- COM>]

Only something anecdotal here, but my users seem to like these two types of
software "manuals" best:

1. The great encyclopedia, discussing everything visible to or significantly
affecting the user. The intent is to provide detailed information. #1 was done
for a mainframe accounting system that completely lacked online help, but was
very consistent in its use of function keys, field contents, etc.
2. Task-oriented Quick Reference cards, e.g., To enroll a student, start this
process. Type this information into these fields. Save the information. Next,
start this process, etc., etc. The QR cards were done for a Windows-based
application that had been ported from the Mac (I think via one of those
third-party libraries like XVT) and (unfortunately) not redesigned to follow
Windows conventions. It follows Mac conventions and even maintains the Mac
"look and feel" -- for example, the *only* way to resize a window is by using
the mouse on the lower right corner, not using any of the borders. (This quirk
is actually kind of unimportant, because 99% of the time, you can't resize any
of the child windows, anyway, no matter how much easier it would be to read it,
or how much higher your display resolution is above plain VGA! Does anyone get
the feeling that I'm not fond of that application? <G>)

Originally, every user of system #1 got their own copy of the encyclopedia.
(Psychological selling point -- you must be worth something if they give you
your own copy of such a tome! <G>)The original version (which seemed to garner
the most praise) also contained the users' departmental procedures. The
procedures included both desk and computer processing steps, specified what
computer process (if any) to use for a step, and (in some cases) gave specific
field values to use. Things were tightly integrated. (It was also *very time
consuming* to create, since it required hundreds of intense hours with the
users.)

The current version of the "great encyclopedia" may or may not contain the
users' departmental procedures (don't have the time), and each office gets one
copy that everyone shares (dratted bean counters!). I haven't heard any
feedback about them; maybe this means that they're simply been shoved onto
shelves and are now being ignored.

Every user of system 2 got their own set of QR cards. They were popular with
(1) managers dealing with new hires -- they could get them started very
quickly, (2) departments that used a lot of temporary help, and (3) users that
occasionally had to do things they didn't normally do. (Also, they fit into a
neat little packet that didn't gobble desk space!)

In both cases, I think the key was the tight linkage between user procedures
and the system documentation. This lets the user link what they already know
(their own procedures) with what they don't know yet (the system). (This works
well for in-house software like I do, but might not be so successful with
shrink-wrap software.)

What do the rest of you think?

To: TECHWR-L @ LISTSERV.OKSTATE.EDU
From: scot @ HCI.COM.AU @ Internet @ DATAHUB
Date: 04/04/96 06:35:48 PM
>In the most part, the manuals I have found that users like the most are
small, compact ones, or "quick'n'dirty" books that might tell you the basic
steps in an unfamiliar procedure. Rarely users will consult a manual to find
out how a particular _control_ works - usually they'll just -- try it and
see for themselves -- , and this is the crux of the arguement. If a system
is implemented with standard Windows controls, there is plenty of info that
tells the users how these work _already_ on their computer; if they won't
read that when told to (in my manual) there's a damn good chance they won't
be reading _my_ manual either.<