DITAblogs (linking)

How we decided what kind of linking to use

Some experienced DITA users employ only relationship tables (located in the master map or in a separate map file). The advantage of this approach is mostly for the producing organization: the links, which are recorded in only one place, can easily be searched and changed if updates to the project require a new linking paradigm. The disadvantage is mostly to the content users, who are given no information about why or under what circumstances they might want to consult the information in the related links.

We have chosen an approach that uses all three kinds of linking: cross-references (xrefs) where contextual information would seem to be helpful to the user ("I'll tell you why might might you want to click this link"), related links to point to external websites, and where the linked information is more along the lines of "I'll give you a few related topics you might want to consult if the titles sound interesting to you," we have used a single relationship table pointed to from the master map. The latter mostly contains "family" links within the core vocabulary section of the document.

To help ensure that our links continue to be accurate throughout the document production process, we run a a set of debugging and link-checking tools we produced ourselves every time we do a major build. The tools check both internal and external (URL) links.