(y)our wiki about all things technical communication

User Tools

Site Tools


Guidelines for creating links

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:

  • Links are less usable when embedded in the text.
  • Longer links are more effective than shorter ones.
  • People scan for target words - the scent of information.

Do not over-use relationship tables

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:

  • Add links for sibling topics if you set the linking attribute to ‘none’ in the parent topic but want to have related links for a select few of the child topics.
  • Add links between topics that would not otherwise be there in the hierarchy of links.
  • Add links to topics outside of the hierarchy in the current DITA map.
  • Keep the number of related links in each topic to fewer than five when possible.

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:

  • <topicref> elements in a DITA map; these have to be the parent topicref elements in the hierarchy.
  • <topicgroup> elements in a relationship table
  • Columns in relationship tables

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:

Collection-type value Description
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:

Question Value
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
dita/guidelines_for_creating_links.txt · Last modified: 2017/03/30 13:16 (external edit)