Writing tasks for online help. Specific vs. General

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Jumping late into this thread, but if I've got the attribution right, 'twas
"D.R. Smith" who wondered: <<Is it better to write a general category with
information included (less topics in the project) or better to have many
topics with short, specific information.>>

The correct answer is that it's better to do both, and that the balance
between them depends on the specific project and subject matter. Online help
should be sufficiently context-sensitive that when you hit the panic button
with the cursor in a field or with a specific dialog box open, you
immediately see the help text linked to that topic. If you use a single
large topic, with many small subtopics, it's often difficult and frustrating
for users to scroll down through dozens of screens to find the one line that
describes the "Type your name here" field or the one paragraph that
describes the "Type your name now" dialog box. Although you can use
mid-topic jumps to accomplish this goal, this can leave the reader stranded
somewhere in the middle of a multi-screen topic with no idea how they got
there or what the surrounding context means. This suggests that it's often
better to create a separate topic for each dialog box--at a minimum. For
really complex dialog boxes (e.g., ones with a dozen tabs), each tab might
conceivably require its own separate topic.

That being said, readers also need higher-level help so they can understand
how all these small topics link together. This is why some help authors
create a single large topic ("entering your name") and pack it full of
dozens of subtopics ("typing letters on the keyboard", "the sublime art of
the Return key", "why Tab isn't a diet drink", etc.). This approach works
particularly well if you expect readers to read or browse a series of
related topics so that (for example) they understand everything about a
dialog box before proceeding rather than just looking up a single field.
Although this approach can work, it doesn't solve the problem of readers who
need to find a specific subtopic within the larger topic. Provided that you
give the reader an efficient means of finding that one subtopic that
interests them once they've arrived within the larger topic, grouping
several small subtopics into a larger topic works just fine. I usually
accomplish this goal by creating a miniature table of contents at the top of
each such large topic. I've occasionally used a "return to begining of
topic" link at the end of each subtopic, but now consider this to provide
little benefit; most people know how to use the Home or Page Up keys to get
to the top of an open window.

A third approach that can also solve your problem requires you to create two
conceptually different types of topics. The first type is the one that I
referred to in my first paragraph, namely a single-function topic that
describes only one thing: a field, a menu choice, or a simple dialog box.
The second type is the one that I hinted at in my second paragraph: a topic
that provides an overview of a larger concept, with links to the appropriate
smaller topics. I find this approach extremely effective because of how well
it meets the needs of readers who want only a single topic explained _and_
those of readers who want the whole tamale. So for example, I might create
separate topics to describe the discrete menu commands for formatting a
page, previewing that format using print preview, then printing the file,
plus a separate "how do I?" topic on printing itself; that latter topic
would explain the need for these three steps, and provide links to the
separate menu topics for each of these steps. The separate topics provide
the low-level specific details; the "how to" topic provides the high-level
details. Cross-references can then provide any necessary or useful
inter-topic links.

Another tremendous advantage of the third approach is that it lets you
create a significant portion of an online help system long before the
programmers have finished tweaking the user interface. In my printing
example, it should become obvious early in the development process that
there are three steps to printing a document, and the broader description of
these steps should appear somewhere in the specifications or design
documents. If you have time to do nothing more than document the existence
and required sequence for these three steps before the product ships, you've
still provided important and useful documentation because many users can use
the high-level description to find their way through the process of
printing. Later in the development process, the user interface for these
three menu choices will stabilize, and you can begin writing the individual
menu topics.

For what it's worth, I've been using the third approach for a couple years
now, and have had quite good reviews from users. We don't bother with
response cards, but I did manage to persuade our trainers to include a "how
to use online help" topic in their training and actively solicit feedback on
the help design and text after teaching that topic. So that's limited but
high-quality data confirming that this approach can work well indeed for
certain audiences.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"I vowed [that] if I complained about things more than three times, I had to
do something about it."--Jon Shear

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.