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

Subject: Defining Terms (Was Re: Judging manuals (by themselves))
From: Steve Owens <uso01%eagle -at- UNIDATA -dot- COM>
Date: Fri, 4 Feb 1994 16:31:20 +0700

> 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

manual - ??

What else belongs in this table?

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

Previous by Author: Passive voice
Next by Author: Spelling Flames
Previous by Thread: Re: Defining Terms (Was Re: Judging manuals (by themselves))
Next by Thread: Re: Defining Terms (Was Re: Judging manuals (by themselves))

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

Sponsored Ads