Technical reports and instructions often require cross-references—those pointers to other places in the same document or to other information sources where related information can be found. (For quick reference, see Summary of Cross-Reference Rules.)
A cross-reference can help readers in a number of different ways:
- It can point them toward more basic information if, for example, they have entered into a document over their heads.
- It can point them to more advanced information if, for example, they already know the stuff you're trying to tell them.
- Also, it can point them to related information.
Related information is the hardest area to explain because ultimately everything is related to everything else—there could be no end to the cross-references. But here's an example from DOS—that troll that lurks inside PC-type computers and supposedly helps you. There are several ways you can copy files: the COPY command, the DISKCOPY command, and XCOPY command. Each method offers different advantages. If you were writing about the COPY command, you'd want cross-references to these other two so that readers could do a bit of shopping around.
Of course, the preceding discussion assumed cross-references within the same document. If there is just too much background to cover in your document, you can cross-reference some external website, book, or article that does provide that background. That way, you are off the hook for having to explain it all!
Now, a decent cross-reference consists of several elements:
- Name of the source being referenced—This can either be the title or a general subject reference. If it is a chapter title or a heading, put it in quotation marks; if it is the name of a book, magazine, report, or reference work, put it in italics or underline. (Individual article titles also go in quotation marks.)
- Page number—Required if it is in the same document. If the cross-reference is to the beginning of a chapter and the chapter number and title are cited (either internal or external), no need for the page number. Readers can use the table of contents. If the cross-reference includes a heading internal to a numbered chapter, include the page number where that heading occurs.
- Subject matter of the cross-reference—Often, you need to state what's in the cross-referenced material and indicate why the reader should go to the trouble of checking it out. This may necessitate indicating the subject matter of the cross-referenced material or stating explicitly how it is related to the current discussion.
These guidelines are shown in the following illustration. Notice in that illustration how different the rules are when the cross-reference is "internal" (that is, to some other part of the same document) compared to when it is "external" (to information outside of the document).
Examples of cross-references. Internal cross-references are cross-references to other areas within your same document; external ones are those to information resources external to your document.
Summary of Cross-Reference Rules
- If your cross-reference contains the title of a book, periodical, or report, italicize that title.
- If your cross-reference contains the title of an article or the title of a chapter or heading, enclose that title in quotation marks.
- If your cross-reference contains something like Figure 1. or Table 2., do not use italics or quotation marks on that item.
- If your cross-reference contains the title of a figure or table, enclose that title in quotation marks.
- If your cross-reference contains a brief indication of the contents of a chapter, use lowercase; do not use italics or quotation marks. This is a minimum requirement for a useful cross-reference.
- If your cross-reference contains a reference to a specific page elsewhere in the same document, include the page number unless that page is the beginning of a chapter (in which case just cite the chapter number).
- If you cross-reference some other document, include the page number only if you cite the document specifics (publication date or edition number) in a footnote or bibliography.
- If your cross-reference contains a reference to a chapter in either the same or some other document, include the chapter number but prefer a brief indication of the contents of that chapter rather than quoting the title.
I would appreciate your thoughts, reactions, criticism regarding this chapter: your response.