In general, cross-references link to nonessential information that adds to the reader's understanding.

References to other documents

  • Give an explanation as to why you are referring the reader to this information.


    Recommended: For more information, see the auth guide.

  • Use meaningful link text.


    Recommended: To begin coding right away, read Building Your First App.

  • If a link downloads a file, the link text needs to indicate this action as well as the file type.

Cross-references within generated reference documents

When linking from one reference topic to another in generated reference documents, use the reference generator's standard linking syntax rather than hard-coding links within the reference, so that the links will change appropriately when the reference docs change.

Formatting cross-references

When a cross-reference is a link, don't put the link text in quotation marks.

Recommended: For more information, see Meet Android Studio.

Recommended: Learn about what's new in Android Wear 2.0.

In the rare case when a cross-reference isn't a link, use quotation marks.

Recommended: For more information, see "Describing system versions," below.

For cross-references that are titles of published works such as books or movies, use italics and title caps but no quotation marks.

Recommended: ... The Chicago Manual of Style and its extremely helpful free online Q&A posts.

Use an external link icon to indicate that the link opens in a new window or tab. For more information, see External link icons.

Recommended: For more information, see Make link text meaningful.