Defining Terms (Was Re: Judging manuals (by themselves))

[Steve Owens <uso01%eagle -at- UNIDATA -dot- COM>]

> Steve notes:
> "I think you missed the point of my "tangent" comment.  I'm not talking
> about STC competitions at all, I'm asking what are the commonly accepted
> definitions of reference/user guide/tutorial/quick-reference/workbook/
> etc."

>     Actually, I didn't, because in my first pararaph, I wasn't talking
>     about competitions either.  You asked what I use as commonly accepted
>     definitions.  The STC comp. guidelines are the closest I've seen to a
>     standard definition.  They're the definition I commonly accept.
>     They're commonly accepted by most of the people I deal with.

        Ah, so you commented on my tangent and then yanked it back to
the original discussion! (There *was* a reason I changed the subject
line, y'know :-).

>     It is a valid question.  We as a profession have got to come up with
>     some kind of standard (open to reasonable variation, of course),
>     because we're confusing the h*** out of our users.

        Not just that, but more important (in my opinion) is having a clear
picture of what we're working on.  If I think it's a tutorial and you think
it's a user guide and we're BOTH calling it a manual, what happens?

>     I don't know the answer offhand to how to solve this -- time for more
>     brainstorming?

        I've noticed that the best way to get people to react is to post
something short and opinionated and let them argue about it :-)  So...

reference - typically aimed at providing complete information for
            quick retrieval without extended committment to reading
            the document.  Usually alphabetized or otherwise sorted,
            lists commands with options, syntax, etc.

tutorial  - typically aimed at a task-oriented, step-by-step analysis
            of the process.  User should be able to sit down with the
            product and the tutorial and perform the task (let's all
            admit it, users NEVER read the tutorial BEFORE trying it -
            I can sympathize, when I start to read something I
            immediately want to try it out).

user guide- typically aimed at a higher conceptual level, more theory
            than process, although process-oriented information should
            be included.

workbook  - typically aimed at a learn-as-you-go level, like a
            tutorial but with more flexibility and assumes more
            freedom to experiment on the user's part.  Should be very
            "sparse", referring the user to the reference, or user's
            guide for detailed information, but should have all
            information for the task at hand (i.e. details of the
            options we're using NOW, but not all the rest of the
            options).

manual    - ??

What else belongs in this table?

Steven J. Owens
uso01 -at- unidata -dot- com