Re: Why We Need Good Software Manuals

[Bonni Graham <bonnig -at- IX -dot- NETCOM -dot- COM>]

Krista Van Laan wrote:

>It seems unrealistic to expect a writer to not only produce a
>user's guide (which should be comprehensive), but then to come up with
>a new twist for on-line help.

Well, it's not really a new twist.  I've watched users in the classes I
used to teach, and almost invariably, they'd go for that F1 key to answer
one of the following questions:

1. What is is? (i.e., context-sensitive reference -- a subset of this is
"what do I type in this field")

2a. How do I do X? (i.e., procedural information, but it had to be brief,
or they'd give up and either get out the book or ask someone)

They'd go to the book almost across the board to answer:

2b. Extended How do I do X? (with some field-reference information for
those fields that aren't obvious, or for procedures that involve multiple
screens/dialogs)

3. Why should I care about this feature/what can I use it for? (theoretical
knowledge)

4. Why did it do THAT? (troubleshooting and problem resolution)

It's not really a new twist, then, it's just locating the information where
people are most likely to look for it.  I've written a paper on this
subject that some of you already have.  I'd be happy to forward a copy to
any additional interested whirlers.

>I'd be annoyed if I searched the manuals for information, couldn't find
>it, and then found it in on-line help. But that's unlikely to happen,
>since I haven't found much on-line help that was easy to use or
>comprehensive. :^)

And I'd be annoyed (and have been, frequently) if I searched the online
help, couldn't find my answer, then went to the book and saw the same
information, which didn't answer my question the first time I looked at it.
I guess it takes all kinds. <g>

I've been structuring my doc sets according to the theory I described
briefly above and have been getting VERY positive comments from my clients.
You don't end up doing a lot of double duty, because you've got to write
the reference anyway, so which tool you write it in doesn't make a whole
lot of difference from your side (at least, it doesn't for me).  For the
procedural stuff, you can either write the online text first then copy it
to the manual and expand, or write the manual first then copy it to the
help and delete.  Not a lot of rework either way.  I've not found that
creating two different sets of information in two different media increased
my time-to-delivery significantly, using this method. YMMV, depending on
the support structure you have.


--
Bonni Graham
Manual Labour
bonnig -at- ix -dot- netcom -dot- com