Avoiding in-text cross-references to topics

Cross-references to other topics should be stored in the relationship table of the ditamap, external to the topic, and not in-line within the text of the topic.

The ditamap's purpose is not limited to specifying the contents of a collection. Automatic inter-topic links are also generated from the ditamap topic hierarchy, and a relationship table section in the ditamap can further extend this automatic linking.

When the same topic appears in a different ditamap, its links will be determined by the hierarchy and relationship table in that different ditamap. In other words, topic-linking is not distributed across many topics, but centralised in the ditamap. This makes maintenance far more efficient.

Cross-references to other topics within paragraphs of a topic can be problematic if the cross-referenced target is not always distributed with the source topic. This can lead to broken links or false assumptions about links being in place.

You should therefore define inter-topic cross-references in the ditamap, using the relationship table (reltable) feature.

There is some evidence that linking outside the paragraph text in this way may be more effective.

I've found that the most effective links are written like headings, not part of sentences at all. I've found that putting links in sentences reduces readability and clickability.

Gerry McGovern