Are there conventions for configuring links to provide targeted assistance in DITA?

Configuring links to provide targeted assistance in DITA XML is a fundamental aspect of enhancing the user experience and delivering precise information when it is needed. DITA conventions offer multiple strategies to achieve this, ensuring that users can access relevant content in an efficient and context-sensitive manner.

One convention for providing targeted assistance is to use key references. Key references are used to link a particular topic to a specific key or identifier. These keys can then be associated with specific elements or locations within the content. For instance, you might use a key reference to link a glossary term to its definition throughout the documentation. Below is an example of how key references can be used in DITA:


<!-- Example of a key reference linking to a glossary term definition -->
<term keyref="glossary-term-key" href="glossary.dita">
  <ph>See Glossary</ph>
</term>

In this example, the <term> element is linked to a specific key, “glossary-term-key,” which is defined in the “glossary.dita” topic. Users clicking on the link will be directed to the glossary term’s definition.

Another convention is to use conref (conditional referencing) for reusing content fragments in different contexts. This allows you to maintain a single source of information and reuse it throughout your documentation, ensuring consistency and accuracy. Here’s an example of conref usage:


<!-- Example of conref for reusing a content fragment -->
<p conref="common-tasks.dita#common-task-step"/>

In this case, the <p> element is referencing a content fragment with the ID “common-task-step” in the “common-tasks.dita” topic, enabling you to reuse this specific step in various parts of your documentation.

By following these conventions and utilizing key references, conref, and other DITA features, you can configure links to deliver targeted assistance and create a user-friendly, context-sensitive help system.