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.
Kathi Jan Knill <<...was wondering what the consensus is on
how often cross-references should be used in printed doc... I
tend to find that it is very distracting to have a lot of
cross-references on a page when I am trying to read.>>
The only standard I'm aware of is "use as many cross-
references as necessary, and no more". That's not too helpful,
but what it really means is that you need to develop objective
criteria for determining whether a cross-reference is really
necessary. These might include:
- If the information cannot be understood without reference to
another source, or if the location of related information on the
topic is not immediately obvious from the table of contents,
then the cross-reference is necessary.
- If a logical or common next step after the current procedure
is to begin another procedure, then a cross-reference to that
procedure is helpful. (Audience and task analysis will tell you
when this occurs.)
- If the text is understandable to many readers, but requires
additional elaboration for others to understand it (e.g.,
referring to a broader explanation of the topic), then a cross-
reference is helpful and may be more efficient than repeating
the information in the current location. Conversely, if the
information will prove essential to a substantial proportion of
your audience, then it's more effective to repeat the necessary
parts of that information rather than providing a cross-
reference.
- If the text refers to something obvious (e.g., like a word
definition in a glossary), then no cross-reference is necessary.
However, you might want to advertise the presence of the
glossary somewhere, just to be sure readers know that you've
provided one.
One way to make cross-refs less intrusive is to place them in
the white space in the margin surrounding the main text
(provided that your design includes such white space).
Alternatively, you can create a separate subheading entitled
"Additional information" or "Related topics", and group all
your cross-references there. In these ways, you move the
cross-refs out of the body text (where they may irritate other
readers like you) and into a convenient place where readers
can learn to look for them. Win-win solution!
