Production notes (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 both cross-references (xrefs) and relationship tables: where contextual information would seem to be helpful to the user ("I'll tell you why might might you want to click this link") we have used xrefs embedded in the content, 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.

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 approximately once a day. The tools check both internal and external (URL) links.