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: Help System See-Also loops From:"Wayne J. Douglass" <wayned -at- VERITY -dot- COM> Date:Tue, 5 Nov 1996 11:00:09 -0800
At 01:34 PM 11/5/96 -0500, you wrote:
>I'm fixing up a help system. Most of the topics have a see-also popup.
>Now, in a lot of cases, the topics belong to logical groups. For example,
>there are topics that describe each of the database commands, of which
>there are maybe ten. Each of those topics has a unique see-also popup
>that refers to all the other topics in the group. This means that there
>are ten almost identical popups. The only difference between those popups
>is that the popup for, for example "open_database" doesn't have a
>reference to "open_database."
>I could save a significant amount of effort if I just used the same
>see-also popup for all the topics in a group. The see-also lists would be
>less likely to miss a topic, since they would be complete lists of topic
>groups. The only downside is that there would be these loops: you click
>on see-also, and one of the options is the topic you are looking at. How
>much pain do you think such a loop causes?
I know that hypertext jumps give writers the opportunity to direct the user
to relevant topics, but this strikes me as useless overkill. My problem is
your use of "groups." Do you mean topics in a browse sequence? If so, then
the user can click the previous or next buttons to get through all the
"maybe ten" topics. If one of your database commands is typically used in
conjunction with another database command, I would link it to the topic that
describes that command and leave out the rest. I understand your temptation
to use a "generic" see also list for all the commands, but it seems to me
that you should be providing intelligence in the material for the user
(that's your added value) and recycling the list doesn't do that. It may be
a maintenance headache, but that's the price you pay for making it easier
for the user. Everything is a trade-off; you be the judge.
I like to use "see also" references to point users to related topics
*outside* the current browse sequence. As the "expert" on the subject, you
can direct users to links that *you* know are related, but the users might
not think of as related. Another good way to use "see also" links is to
point readers of a reference topic (a description of menu options, for
example) to the related "how-to" topic, and vice versa.
Verity, Inc. Email: wayned -at- verity -dot- com
894 Ross Drive Telephone: 408-542-2139
Sunnyvale, CA 94089 Facsimile: 408-542-2040