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.
René wondered: <<I'm reviewing a (java)help document that has been
critised as having excessive hyperlinks in each topic, such that
readers are easily diverted and become 'lost' from the original topic
that they were reading.>>
If the people doing the criticizing are representative of the actual
readers of the document, then it pays to listen carefully to what
they're saying. Even if they're not, it still pays to listen: they
may be wrong, but you won't know that until you understand why
they're complaining and whether it's a good reason. (When in doubt,
assume the reader knows more than you do about their own needs. <g>)
<<A silly question, I admit, but is there is consensus or general
rule of thumb as to what consititutes "excessive hyperlinks"?>>
Yup: they're excessive if there are more of them than necessary. <g>
Sorry to be a bit facetious, but that's really the only useful answer
to your question. That being said, the problem becomes one of
determining how many are necessary:
<<Is the answer to simply reduce the hyperlinks?>>
It depends. <g> No, really. If the hyperlinks are simply additional
useful information that some reader might possibly be interested in,
then gather them together at the end of the topic as a series of
"related topics". If you need to understand the contents of each
hyperlinked topic before you can understand the current topic, then
you should consider integrating that information within the current
topic rather than forcing readers to leave the current topic.
If the links are to material that is of general interest, then you
should gather it into a single "what you need to understand before
reading any further" topic, and add a line such as the following at
the start of the current topic: "If you do not already understand
[description of the general information required to understand the
current topic], read [hyperlink] first." I like to open the new topic
in a new window so that closing the new window immediately returns
readers to their original context and that it's easy to become "lost
in hyperpace" if you follow a fruitless series of links in a single
window; the "back" button won't always help. Recognizing that many
users abhor an endless spawning of new windows, I won't open more
than one new window: those who want more can do this themselves.
As a general rule, any help topic should begin with a brief overview
of key context: information that tells the reader they've found the
correct topic (ideally, the title of the help topic should be all
that's necessary). Next, provide an overview of any crucial context
that won't fit in the title: steps that must be completed before you
begin pondering the steps in the current topic, warnings of various
degrees of seriousness, information on who can and cannot perform the
steps in the current topic (e.g., if you need administrator rights or
an advanced degree in physics), and a discussion of the various
alternatives (use approach A if..., use approach B if...). Continue
with links to anything that readers should understand before they
read any further, then present the actual text of the current topic.
Conclude with links to information that is useful (to get the most
out of the current information) but not essential. Essential
information belongs right in the topic.
For longer or more complex topics broken into several sections,
repeat this structure for each subtopic presented in the same window,
and if there are several of these, consider starting the window with
the text "This help topic contains the following sections", followed
by hyper links to each section. There's some debate about the use of
these mini-TOCs, but I personally find them so useful I can't imagine
anyone objecting much to their presence. (Possibly a failure of
imagination? <g>)
<<Should the document change from object orientated (now) to more
task orientated (future)?>>
If it's a reference manual, then focusing on the meaning and use of
each object in the interface is perfectly appropriate. If it's a user
manual, focus on the tasks, and provide links to any reference
material that is incidental to the tasks. Any reference material that
is crucial to performance of a task and that readers can't be
expected to already know belongs directly inside the task description.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
