It is easy to over-use inline links in your text, making it confusing to the reader. It is important to use them only when necessary and keep in mind the following guidelines:
Keep your topics short and self-contained. These links can become difficult to maintain when you update your topics, for instance by deleting a table or moving it to a different topic. They can also make it difficult to re-use topics. Instead, you can consider re-using the table or the figure somewhere else in the form of a content reference.
You might use phrases such as ‘Repeat step 2 to add each topic to the DITA map’. In this case you will need to update this phrase every time you add a step before ‘step 2’. You can solve this by adding an <xref> element that links to the relevant step. In doing so, every time the numbering changes in the steps, the <xref> element will ensure the text changes automatically.
If you have a manual that contains a task flow with too many task topics, the user might start to lose track of the big picture. As these tasks might be spread throughout your DITA map, you might not be able to take advantage of the default linking system. In this case, you can use inline links to show users a roadmap of the task flow they will have to follow. This way, they can plan for tasks they will need to complete in the future.
For all their advantages, inline links are not without their flaws. Tests conducted by Jared Spool support the view that links outside of the text are more effective than inline, embedded links. Spool’s study concluded that:
Relationship tables are useful in linking content that does not get connected by the hierarchical linking system. Still, it is important not to start linking too much. What applies for inline linking, applies for relationship tables as well. Too many will only confuse the user.
A good general rule to keep in mind is that hierarchical linking is nearly error-proof and low maintenance. As such, it is a good system to rely on. Only start adding relationship tables if you need relevant topics of information to be linked for the user’s convenience. When you do, follow these guidelines:
A collection type defines a relationship among nested topics and affects the way in which automatic links are generated in the output of your DITA map.
You create a collection of links by setting the value of the @collection-type attribute, which defines how the nested topics are related. You can apply the @collection-type attribute to:
Although @collection-type attributes are valid in relationship table relcell elements, some don’t make a lot of sense in that context. For example, if you set a @collection-type in a relationship table cell to ‘sequence’, it will result in a Next Topic link in the output linking to the next topic referenced in the cell, rather than to the next topic in the TOC sequence (as may logically be expected by the reader).
You can set the values of the @collection-type attribute to one of the four following values:
|choice||Not commonly used, but it is intended for situations where the reader needs to select one child topic to proceed. This may be useful when the output document is an interactive decision-support application. Most processors treat choice in the same way as unordered.|
|family||Links are generated from parent to children, from children to parent, and from sibling to sibling.|
|sequence||Links are generated from parent to children, from children to parent, and from child to previous sibling (if applicable) and next sibling (if applicable). It creates a numbered sequence.|
|unordered||Links are generated from parent to children, and from children to parent. These links can be completed in any order.|
The following table can help you decide which type is most appropriate for your situation:
|Should the nested task topics be completed in a particular order?||Sequence|
|Do the topics represent choices?||Choice or family|
|Can the task topics be done in any order?||Unordered or family|
|Are the topics closely related and need links between sibling topics?||Family|