Use cross-references to direct users to related information that might add to their understanding of a concept.
Try to write and edit so that you use cross-references only for information that is not essential to the task at hand. For example, users should not have to look up information to complete a procedure. If your content has too many cross-references, consider restructuring it.
Content for a technical audience can have more cross-references than content for a general audience.
Different teams have different requirements and methods for referring to other information. Always consult your project style sheet for how to use and format cross-references.
Do not provide cross-references to a product or service, its user interface, or its application programming interface. Refer only to content about the product or service.
Microsoft style
For information about available storage formats, see Saving your document.
Not Microsoft style
For information about available storage formats, see the Save As dialog box.
Unless you have no other choice, do not make cross-references to information that is not within your control, especially hyperlinks. Websites are always being modified and reorganized, and few things are as frustrating to the user as an invalid cross-reference.
Do not use blind cross-references. They provide no information about why you are using the cross-reference. The user should know whether it is worth interrupting the current topic for the cross-referenced information before following the cross-reference.
Microsoft style
For more information about modifying Visual Basic source code and installing Visual Basic forms, see Chapter 9, “Extending forms.”
Not Microsoft style
See Chapter 9, “Extending forms.”
It is all right to use blind cross-references in a “See also” or “Related links” type section or at the end of glossary entries.
Information about why a cross-reference might be of interest should precede the cross-reference itself. That way, if the reason for following the cross-reference is not compelling, the user can move on quickly.
Microsoft style
For more information about modifying Visual Basic source code and installing Visual Basic forms, see Chapter 9, “Extending forms.”
Not Microsoft style
See Chapter 9, “Extending forms,” for more information about modifying Visual Basic source code and installing Visual Basic forms.
For cross-references that provide additional information, use “For more information about,” not “For more information on.” Many non-native English speakers have trouble with the latter phrase.
If the cross-referenced information provides an extended discussion of the current topic, the introduction to the cross-reference can be general.
Microsoft style
For details, see Chapter 9, “Extending forms.”
For cross-references to books or manuals, provide both a chapter number and title. If the cross-reference is to information in the same chapter or short document (such as an article or white paper), provide a section title. In this case, explicitly note that the cross-reference is to the current chapter or document. Use earlier or later, not above or below.
If a cross-reference is to a section within a chapter or to a chapter in another publication, structure the cross-reference from the most specific to the most general reference, that is, section first, then chapter, then book title.
For information about creating new pages, see “Working with page files” in Chapter 6, Creating your pages.
For information about arithmetic conversions, see “Usual arithmetic conversions” earlier in this white paper.
Not Microsoft style
For details, see “Extending forms.”
For information about creating new pages, see Chapter 6, Creating your pages, under the topic “Working with page files.”
For online cross-references that are formatted as hyperlinks, use descriptive text for the hyperlink; do not use an empty expression, such as “Click here.” If the hyperlink comes at the end of a sentence, do not make the ending punctuation part of the hyperlink.
Microsoft style
For more information about modifying Visual Basic source code and installing Visual Basic forms, see Extending forms.
Not Microsoft style
For more information about modifying Visual Basic source code and installing Visual Basic forms, see Extending forms.
For more information about modifying Visual Basic source code and installing Visual Basic forms, click here.
Web-style hyperlinks, in which the reason for the cross-reference is implicit in the text, can be effective. Ensure, however, that the purpose of the link is clear.
Microsoft style
You can save your document in a variety of storage formats.
Format cross-references by using sentence-style capitalization, even if what you are referring to uses title capitalization.
Microsoft style
For more information about modifying Visual Basic source code and installing Visual Basic forms, see Extending forms.
Not Microsoft style
For more information about modifying Visual Basic source code and installing Visual Basic forms, see Extending Forms.
The style of providing “See also” sections can vary, depending on the needs of the audience and the type of content that you are writing. For example, a “See also” section in a programming reference is usually very basic, providing only blind cross-references to documentation for programming elements similar to the one under discussion. A “See also” section in a white paper, by contrast, might provide extensive information about each cross-referenced item.
Titles of “See also” sections can also vary. For example, such sections might be called “Related topics” or, for cross-references that are exclusively hyperlinks, “Related links.” These sections can be formatted as pop-up windows, lists, or even marginal text. Because such variations are project-specific, consult your project style sheet, and be consistent in the way you format these sections.
Do not make cross-references to untitled or unnumbered art or tables unless the art or table immediately precedes or follows the reference.
Cross-references that appear in the margin of a document can direct the user to additional help or ideas without interrupting the flow of the main text. These marginal cross-references can follow standard cross-reference style, using a complete sentence and ending with a period, or they can include a graphic (such as the Help button) with a heading and the cross-reference. Use a consistent format within your content.
Microsoft style
For more ideas, see
“Writing and correspondence”
See Getting started
The following are some basic guidelines for marginal cross-references:
Do not clutter a page with too many marginal cross-references; some teams limit notations to three per page.
Try to limit marginal cross-references to about three or four lines. They expand when localized.
Break lines so that they are about the same length.
Follow the design for a specific project to determine whether to apply character formatting in marginal notations.
For more information, see Art, captions and callouts; Marginal notes; Notes and tips; Tables