Cross-References

[Charles Fisher <decrsc!charles -at- UUNET -dot- UU -dot- NET>]

Hi All -

Here's a question for you on a (rainy) Monday morning:

How do you handle cross-references in your documents? What parts do you
include? Section Name/Page Number/Book Title? Any Combination? Do you
treat cross-references to other manuals/books differently than xrefs to
another part of the same book? Do you treat xrefs within one chapter
differently than xrefs across different chapters of the same book? Do you
ahve any rules about what level of the document you xref? How do you
manage your xrefs for updates or change pages?

The reason I'm asking these questions is to find out if there's a better
way for us to set up and manage our xrefs. Currently, we have three
"types" of xrefs:

  1. Xrefs within a document
  2. Xrefs to another Datatel document
  3. Xrefs to external documents.

The xrefs get less and less specific as you go down the above list. For
example, we include section title and page number for internal xrefs,
Document title and chapter title for xrefs to other Datatel docs, and
Document title and general information topic for xrefs to external
documents (external in the sense that they're documents we don't produce,
such as the MS Windows Users' Guide).

Our "rule" for internal xrefs is not to xref anything lower than the
second level of heading, with the exception of figures and tables.

The problem that we're having is that when we develop and send out change
pages for a document, we run the risk of changing the pagination of
something that's cross-referenced. For example, if we change pages 5-10
through 5-14, and something that originally appeared on page 5-11 is now on
page 5-12, any xrefs to that something that appear in other parts of the
book all read "5-11" and not "5-12" unless we either send out all the
pages on which the xref appears or change the way we xref things. [Sorry
for the loonngg sentence.]

We're also fighting the battle here of "what's easier for us to do" vs.
"what's more useful/helpful to our clients." My opinion on this issue
is that we need to do whatever makes the document more useful, even if it is
a pain for us to do. However, there's got to be a good method out there
that does a little of both.

BTW, we're using FrameMaker here, which allows you to develop a list of
xrefs for a book file. However, I've run into some problems with this that
Frame is investigating.

Thanks for listening. I'll take any advice you can give....
--
"If you take hyphens seriously you will surely go mad."
  -John Benbow
--------------------------------------------------------------------------------

Charles Fisher
Senior Documentation Specialist
Program Manager/President-Elect, STC Washington DC Chapter

Datatel, Inc.                (703) 968-4588 (voice)
4375 Fair Lakes Court        (703) 968-4625 (FAX)
Fairfax, VA  22033           charles -at- datatel -dot- com