Are there guidelines for choosing meaningful cross-reference text in DITA?

When creating cross-references in DITA, choosing meaningful cross-reference text is crucial to enhance the clarity and usability of your documentation. Meaningful cross-reference text provides context to the reader, helping them understand the purpose of the link without having to click on it. Here are some guidelines to consider when selecting meaningful cross-reference text:

1. Be Descriptive: Cross-reference text should succinctly describe the linked content. Use terms that clearly convey the topic, section, or purpose of the link. Avoid vague or generic descriptions that may leave readers uncertain about the link’s destination.

2. Keep It Concise: While being descriptive is important, it’s also crucial to keep the cross-reference text concise. Long and verbose text can clutter your content and make it harder to read. Aim for brevity while maintaining clarity.

3. Use Action-Oriented Language: If the cross-reference leads to an action or a task, consider using action-oriented language. For example, use “Learn more about topic X” or “Read the details on procedure Y” to guide readers on what to expect when they follow the link.

<!-- Example of meaningful cross-reference text in DITA -->
Learn about Safety Procedures

In this example, the cross-reference text “Learn about Safety Procedures” provides clear and concise information about the linked content, helping readers understand what they’ll find when they follow the link.