Cross-references are a means of binding individual topics into a coherent and navigable document.
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
A cross-reference is used in DITA to link or associate one piece of content with another. The cross-reference (xref) element is the primary mechanism for cross-referencing, but other elements also have cross-referencing functions.
The cross-reference element is used for linking or otherwise cross-referencing text within a topic to other topics, elements within a topic, or resources external to the DITA collection.
Cross-references to other topics should be stored in the relationship table of the ditamap, external to the topic, and not in-line within the text of the topic.
Cross-references are commonly made to other DITA topics in a collection, and to information resources outside the collection. These external targets can be any type of electronic resource that can be addressed through a URI, including e-mail addresses, documents on a network file server, and Web content.
Cross-references to elements within topics such as figures and tables allow a reader to easily navigate through a document, whether it is in a page layout format or a hypertext format. The xref element is always used for cross-referencing elements within a topic.
When a topic requires cross-references to other topics where those cross-references will always be valid in the context of the topic, they should be contained within a related-links section after the topic body. In all other cases, cross-references should be defined in the relationship table of the ditamap.
Cross-references to ditamaps should not be used, because DITA does not have a clear method for doing so, and the logic of linking to metadata is not strong.
Related links can be removed from the output by setting the linking attribute of the topicref element in the ditamap to none. If you are producing HTML-based output, you can alternatively change the CSS class definition so that generated links are not displayed.
The standard DITA metadata attributes of audience, platform, product, and otherprops can be applied to xref elements to allow conditional processing of cross-references. Positioning cross-references at the end of a sentence makes it easier to exclude the cross-reference without affecting the sense of the sentence.
You should not use cross-reference elements within topic titles.
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.