Technical documentation, traditionally, is heavy on cross references. We often need to refer to other documents in the documentation set, or help the user find other relevant information within a long document.
But cross references present us with two problems:
- What if the target topic moves?
- How do I make sure the link is still relevant if the topic is used in several different deliverables?
Many DITA practitioners recommend avoiding inline cross references, because they potentially distract the user from the content they are reading. As the web matures and as best practice around writing links emerges, I think readers are quite capable of negotiating hypertext. However, more to the point, inline links in their traditional form can inhibit reuse – placing a cross reference inline in a topic potentially adds context to that topic – giving it a fixed meaning that the topic otherwise may not have.
To an extent, we can get around the problem using a relationship table to manage all the links between topics in one place. But as well as being fiddly to maintain and hard to read, you still have to know exactly where you are linking to, and that link can be broken if the target topic moves.
The most important thing about keys is that the target topic is like a ‘logical topic’. We can point somewhere, but we don’t have to know straight away where or what the reference is pointing to. That give us the option to manage them externally from the topic while still having the freedom to place them inline if that is what works for the content, but more importantly we can avoid having to update a link in multiple places if it happens to change.
Managing external links
In this example we’ll look at how to define an external link as a keydef so that it’s easy to cascade changes through a map, while maintaining the portability of individual topics.
The email link to the acmecorp regional support desk is defined by a keydef element in the map, called SupportEmail:
In the topic ‘Activating your licence key’ the link is written as an xref element with the keyref attribute set to SupportEmail:
In a long document that may refer to the support desk many times, instead of writing out the email address each time (then potentially having to do an extensive find and replace operation when it changes) we can simply reference the key in the map.
We can then create a different map, for example a US installation guide, that uses the same topic, but with links to the US regional support desk:
The topic ‘Activating your licence key’ is the same topic as used in the EMEA region map – but the link points to a different URL:
So if the email address of either support desk changes, it’s much quicker and more reliable to implement that change because you’re only changing the keys in the maps rather than every place in the document where the link occurs.
Managing internal links
We can apply the same principle for links between topics within a map:
In the XML itself, the map looks like this:
Defining a key for each topic in the map enables you to create cross references between those topics that only apply within that map, and that don’t require you to change the cross reference itself if the topic changes.
The keyref “Sysreqs” points to the key definition “Sysreqs” associated with the topic reference in the map – not to the topic ‘Systems requirements’ itself. This means that you could replace that topic reference with a reference to a different topic, and, as long as it still had its key definition the cross reference would remain intact.
Defining keys for each topicref in the map becomes extremely useful when you are cloning maps. It’s very common to start a new deliverable based on an existing one – copying a map that you then change to meet a particular need. If you clone a map where the cross references between topics are managed by keys, they will continue to resolve correctly even if the target topic itself changes.
Next time we’ll look at the @conkeyref attribute and how to use keys to manage referenced content.
View more Bitesize DITA tips, tricks and insights
If you have a question or a useful tip to share, why not tweet us @BiteSizeDITA
DITA Training
Looking to develop your DITA skills? Book your place on one of our DITA training courses. Mekon offer a range of DITA training to suit your specific needs:
Our specialist training courses can be delivered as a standalone training course, or as part of an integrated, customised solution. We deliver our courses in a number of ways, here at Mekon, on site with you or remote.