Re: Simple Economics

Subject: Re: Simple Economics
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: "Jeanne A. E. DeVoto" <jaed -at- jaedworks -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 22 May 2000 07:49:10 -0700 (PDT)

--- "Jeanne A. E. DeVoto" wrote:

> 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.


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.

Andrew Plato
How's that working out for you? Being clever:

Do You Yahoo!?
Send instant messages & get email alerts with Yahoo! Messenger.

Previous by Author: HUMOR: Conference Schedule
Next by Author: You're a contractor when...
Previous by Thread: Re: Simple Economics
Next by Thread: Fwd: Thanks! (re UNIX questions)

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

Sponsored Ads