Cross-references

Cross-references, usage

Use cross-references in documentation to direct users to related information that might add to their understanding of a concept. Unless the information is essential to the task at hand, do not repeat information provided in another topic—reference it. However, try to write and edit so that you use cross-references only occasionally for information that is not essential to the task at hand. For example, readers should not have to look up material to gain a complete understanding of a concept or procedure. If the material has too many cross-references, restructure it. Technical material can have more cross-references than non-technical material.

On the other hand, material on the Web can benefit from links to other web pages and even to sections on a long page. Links to bookmarks, used judiciously, can shorten long pages and help users find exactly the material they want.

These guidelines are intended for local references within your own document, printed and online.

Syntax of cross-references

Start a cross-reference by telling users why they should look elsewhere, not where they should look, even if the reason is not specific. For links to websites, don't use a phrase such as “click here”. Make the cross-reference text a hyperlink.

Correct

For more information about scheduling parameters, see Chapter 9 “Scheduling”.

For more information, see Chapter 9.

For information about scheduling parameters, see Scheduling.

Incorrect

See Chapter 9 for more information about scheduling parameters.

For more information, click here.

Do not use above and below in cross-references in either printed or online documentation. Use previous, next, earlier or later, give a more specific reference, or include a link to an online topic or website.

Use the following phrasing for referencing different parts of a document:

Referencing document parts

see the “Haulage” topic under “Transportation Methods” in Chapter 5.

see the “Transportation Methods” section in Chapter 5

in this chapter

see Section 4.1.5

see Chapter 4 “Site Recovery Plan”

see Figure 8

(Figure 8)

refer to Figure 8 at Attachment 3

refer to Figure 8 in Appendix B

in Table 3.4

see Glossary

Cross-references in online documentation

Most online cross-references are jumps to other topics, such as how-to information from overviews and conceptual information. “See also” or links to “Related topics” can appear either in a non-scrolling region after the topic title or at the end of the topic. This kind of reference can refer both to other Help topics and to book titles.

If you include a cross-reference jump or link within a topic, use wording similar to the following.

Correct

For more information, see Customizing and Optimizing Word.

For more information about adding fonts, see Customizing and Optimizing Word.

Cross-references in printed documentation

There are a number of ways to handle cross-references in books and reports:

• Within or at the end of a paragraph, when a cross-reference is appropriate to a specific context.

• In the margin, when a cross-reference applies to a topic or section that appears on that page.

• With a subheading, generally used in designs for technical references.

Formatting cross-references

Follow these capitalization and punctuation guidelines for cross-references:

Note

The format of bibliographic references (to cited documents in a References section) follows an entirely separate set of rules. See Bibliographies and citations for more information.

• Only capitalize references to parts of your own document (that is, local cross-references). In general, use a bibliographic style when referencing other documents. For example, “...Abbott & Clarke (2008, s. 5.2) recommend...” or “...in section 5.2 “Closure and Rehabilitation”, Abbott & Clarke (2008) recommend...” or “...section 15A(4)(f) of the Act provides...”

• Follow the capitalization style used in the titles and headings of your document, but as a general guideline use sentence-style. If you list an Internet address in printed documentation, follow the capitalization as it appears in the URL, which usually is lower case.

• Italicize book titles in both printed and online documentation.

• Use quotation marks around titles of sections and chapters. Do not include the word chapter or its number within the quotation marks: Chapter 7 “Formatting”.

• Capitalize the word chapter, section, appendix, table, or figure when it refers to a specific number, as in “see Chapter 7” in your own document (local). Use lower case when no number is mentioned, as in “earlier in this chapter” or when referencing another document. Plural references are capitalized for consistency, as in “Figures 4.3 and 4.4”.

• Capitalize index, glossary, and appendix in local references such as “see the Index”.

• Capitalize local references to uniquely numbered sections and clauses of a report. When referencing clauses (numbered paragraphs), ensure that the reference is unique.

• Do not capitalize references to pages, footnotes, notes, unnumbered paragraphs or sections, nor numbered or labelled list items.

• Do not use abbreviations (Ch., App., Fig. etc.) unless space is a consideration.

Correct

in the Index

in the Glossary

in the previous chapter

in the following table

in Table 3.2

For more information, see Chapter 3.

Chapter 8 “Methods of analysis”...

Refer to Appendix B for ...

(see Section 3.2.1)

refer to Figures 8 through 11

...—refer to Clause 3.2.1 (a)—

Figure 6 shows ...

Cross-references to art

Do not make cross-references to untitled or unnumbered art or tables unless the art or table immediately precedes or follows the reference on the page.