TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Need doc set advice From:Mike Pope <mikep -at- ASYMETRIX -dot- COM> Date:Thu, 28 Jul 1994 12:41:00 PDT
>I'm documenting a fairly simple GUI application for users who are not
>particularly knowledgable about using software. Users can fill in forms to
>search a database for information and update that information. When I
>this job, the doc set consisted of the following pieces:
>Reference Manual, organized by menu
>Tutorial, organized by major task
>Quick Reference Card, organized by task
>Users complained that the Tutorial was too long and intimidating, so I
>Quick Start manual. This piece presents a subset of the tutorial.
> folks in the field like to use the Tutorial for training, so I can't dump
>I'm toying with the idea of converting the Reference Manual to a
>format. Instead of having chapters called File Menu, Edit Menu, etc., I'd
>have chapters like Searching, Updating, etc. This piece would be the
>for all information about the application, from soup to nuts.
>o Given that I have a fairly detailed Tutorial, do you think a
> User's Guide would be redundant?
Is the tutorial itself organized by tasks? Does it have the same sections
are proposing for the task-oriented-no-longer-a-reference manual?
This is speculative, but I would see the Tutorial as a walk-through: watch
do the 6, 12, 22 most common things that ones does with this program. I'm
going to go into exhaustive detail, I'm just showing you some stuff. If
or if you've done some of this before, this may be all you need to get
The task-oriented section, on the other hand, presents the conceptual
background required to understand the purpose of the procedures.
"What does it mean to search?" "What does it mean to sort/order data?"
"What is an index?" etc. This section would also be more exhaustive -- if I
you the 12 most common things in the Tutorial/Walkthrough, well, here's
learn the rest. To save trouble, you could theoretically refer them back to
Tutorial for procedures already covered there. That might not be as odious
as it sounds,
since most people are probably not slogging through the task-oriented
section page by
page; they are probably just looking for one procedure, and the index can
take them to
the Tutorial instead of to this section. Dunno, you'd have to try it.
o How valuable do you think the menu-based organization is for a fairly
> GUI application?
The presumption of such a section is that they're staring at the screen and
about something they see there. "I chose Edit-Find, and now I don't know
what Match Case
means". I assume, anyway, that that's what the sort of information that the
If so, that type of information is more typically provided in online Help,
especially if you
can provide hypergraphics that allow people to click on the prompt or
whatever that they're
Just thinking out loud. I might be misinterpreting your questions, and
bit too freely from your descriptions. If so, just pay me no never mind.