Improve Your Relationships. Where to Code Links? Best practice.
Authors working in FrameMaker or Word have hard-coded links within topics to other topics using cross-references. When moving to DITA, authors often tend towards hard-coding links in topics, inserting cross references or using the element.
What’s wrong with hard-coded links?
They decrease reusability, they tend to break, they tend to get out of date, and they are high maintenance.
- Decreased reusability: hard-coded links may not make much sense when a topic is reused but if you hard-coded the links you’re stuck with them.
- They tend to break: if the target topic is renamed or moved, the link will break.
- They tend to get out of date: if a related topic is added, the author would have to look in many topics, find the appropriate locations and insert many times the appropriate link.
- High maintenance: see reasons 2 and 3 above.
Hard-coded links are not in a good idea in FrameMaker or Word, but when working in unstructured DTP tools you didn’t have much choice. In DITA you do — and you should use it. “Relationship tables” in DITA allow you to control linking from one place, for many topics, rather than hard code links within many topics.
It’s not often that this blog for power authors is able to offer relationship advice, but today we are. Use relationship tables and start improving your documents!
Best wishes,
Abby, … oops, I mean Katriel
