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.
>
> But if I'm documenting, say, a billing application, the "reference" is
> going to consist of things like lists of menu items and information about
> dialog-box controls. It's potentially helpful to some users, yes...but not
> as useful as task-based help. The documentation for any product needs to be
> accurate and useful, and while reference help for this kind of application
> can be just as accurate as the task-based help, and it might even cover as
> much territory as the task-based help, it's not going to be anywhere near
> as useful. Here starting with the reference would be a mistake, because
> it's likely to be less complete and certain to be less useful than its
> task-based counterpart.
Nope.
If you're documenting a billing system the "reference" information is going to
be answers to questions such as "what does this system do?", "what does it
process?" "what is the entire billing cycle?" "how are billing system needs
represented in this application?" and other related, conceptual information
which may have nothing to do with the user interface.
The menus on the UI are incidental to the function and purpose of the system.
Once you educate the reader as to what they are supposed to do and why
something exists - explaining how to do it is a total no-brainer.
Basically, information breaks down into the following hierarchy:
1. Premise: what lead up to the existence of this thing.
2. Concept: what is this thing's purpose in life.
3. Task : how do you use it.
3 cannot exist without 1 and 2. But 1 and 2 can exist without 3. If readers
don't know why something exists, explaining how to use it is a waste of time.
It is like telling a 3 year old how to fund a 401K. The 3 year old does not
know what a 401K is or how it helps him/her. Giving him/her instructions on how
to fund one would be meaningless.
A lot of writers become obsessed with 3, because 3 is fun and easy and feels
important. In fact, 3 is the LEAST important aspect of tech writing.
Documenting tasks is a breeze and a half if you have prepared the reader,
intellectually, for the concepts.
1 and 2 are complex and require a lot more intellectual brain power to handle.
They also require a deeper understanding of what the system is, does, and can
do, which usually means a visit to the engineers and other individuals who
designed the system.
