The related-links element

If three-fourths of the Earth’s surface is water, why is it still so easy for me to lose things in that correspondingly smaller amount of land? It seems like I’m always looking for misplaced things. If all those lost things just had a proper storage place, and I knew where that was, it would be so much easier to account for all my gear–especially missing car keys!

For keeping track of links, at least, DITA offers two solutions. First is the DITA map, which maintains all links centrally. If you remove a topic from the map and rebuild the map, the remaining links are still fully valid because the map only links to resources it manages.

The other link management approach in DITA is to maintain a subset of links directly within the topic, however not in the body of the topic itself. DITA topics provide a structure called related-links where, if your information architecture requires it, you can maintain in one place all the links that pertain to your topic.

In theory, you could develop a full web of information using only these internally located links, not using a map at all. In practice, you’ll generally find that the map elegantly takes care of managing the overall relationships of the topics to each other, while the related-links element is excellent at managing links to resources outside of the web of topics themselves, but local to the topic. This includes using it to manage collections of associated PDFs and downloadable files, links to other web sites outside of your own (as I’m using the Deep Dive link list below), and, as needed, directly to other topics within the collection (although the map’s relationship table can do that for you, relieving you from having to maintain those dependent links within the topic).

Did you know?

Just for fun: Only a few elements in the base DITA topic type have a hyphen in their names like related-links does. Which others can you name before you peek? When you are ready, highlight the rest of this paragraph to see the full list of DITA 1.2 element names that have hyphens:  [related-links, required-cleanup, draft-comment, data-about, index-base, index-see, index-see-also, index-sort-as, no-topic-nesting]

Deep Dive

Leave a Reply

Your email address will not be published. Required fields are marked *