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.
What guidelines are used for including cross-references (X-refs) to tables,
figures, sections, etc.? We use MSWord95 and its automatic X-refs feature.
Although X-refs are generally helpful for both paper and online documents,
we are coming up against a few issues:
* Do unnecessary, or excessive, references present "speed bumps" to
the reader? Excessive use of X-refs can indicate structural problems with
the document, but how many are too many? How can you determine if an X-ref
is needed or if it adds more noise than it is worth?
* Page number references make no sense in online documentation. In
Framemaker this can be solved as X-ref formats can be changed globally (just
like styles). This allows all the X-refs with page numbers document destined
for paper to be quickly changed to X-refs without page numbers. No such luck
in MSWord95. As we try to single-source documents for paper and various
online solutions, should X-refs with page numbers be avoided?
* X-refs are prone to error when documents are revised. MSWord for
example, quietly inserts "Error! Reference source not found" at the location
of the broken reference and does not warn you of this. The broken link may
not get noticed until the customer reads the revised document, unless you
perform a "search and repair" every time a document is modified.
(Framemaker, to its credit, generates warnings if a X-ref link is broken.)
The more X-refs in a document, the more vulnerable it is.
Any suggestions or additional caveats would be appreciated.
Please, no Frame vs. MSWord manifestos. Most of us know the pros and cons of
each, and we'll use whatever our employer/client wishes us to use, unless we
get make a recommendation. Presently, my company's department uses MSWord95
so my interest lies in solutions that work for it. ;)
TIA
David Neufeld
=======================================================================
Technical Publications
Spectrum Signal Processing, Inc.
dave_neufeld -at- spectrumsignal -dot- com
http:\\www.spectrumsignal.com
"no matter where you go..... there you are." -- Buckaroo Banzai
