Linking topics: Cross-reference or relationship table?

Choose the appropriate reference type, cross-reference or relationship table, to link between topics so you and your readers get the most from your documentation.

When you’re moving from less-than-structured documentation to topic-based writing, one of the less apparent challenges is to link your related topics to one another. You could just keep on using cross-references, but then you’d miss out on some of the benefits of topics.

Whether you write topics using a standard like DITA or a tool such as MadCap Flare, you have a new cross-reference type, relationship tables. It is important to distinguish the two types, because each serves a unique purpose.

Cross-references

A cross-reference is the link you know from Word or other document-based writing: You create a link to a heading or a bookmark, it can show the heading title, and it updates automatically if that heading (or a page number) changes.

It leads readers from a certain point or condition to another place. It tells readers:

If you want to do or know that now, go over there.

So far, so good. This kind of link works well, if you have a document with an organised sequence. Occasionally, you need to offer the reader an occasional branching into two alternative secnarios or a jump to another place.

But when you convert your content into a pile of loosely connected topics, you have much more demand and more opportunities to relate topics.

Disadvantages of cross-references

Cross-references aren’t always the best way to relate topics because they:

• Disrupt reading flow and orientation. For users, it’s fine to make the occasional choice between scenario A or B. But offering too many links will tempt many users to wonder what they’re missing at the other end. And following link after link from within one topic to the next quickly breaks the flow of tasks and leaves the user confused.
• Create a web of dependencies. With cross-references, you tie your topics to one another in a certain preferred scenario you engineer. This scenario may not suit the user’s current need. It undermines the flexible “stand-alone” independence of topics that supports multiple use cases. And it makes it harder for writers to reuse them.

So while cross-references are easily a preferred way of linking contents in document-based writing, consider carefully how they will affect your use, and the users’ benefits, of your topics.

Cross-references in topics work well in these cases:

• Link to mandatory pre-requisites or required next steps.
• Link to a series of tasks in an overview/parent topic.

In either case, the user pretty much must follow the link to achieve anything useful, so cross-references are fine. Just make sure that the link and the surrounding text are meaningful, so users can decide whether they should follow the link.

– So if cross-references are not always recommended, how else can I link between topics?

Relationship tables

A relationship table is best to indicate that certain topics as a whole are related. It tells readers:

If you’re involved with this topic, you should also be aware of those topics.

For users, links from relationship tables appear separately, usually below the actual topic text in a section of related links or “see also”, depending on how you choose to style them.

For writers, under the hood, a relationship table is a separate file that lists by type which topics are related to one another. For example, I could have a table like this:

Concept topics	Task topics	Reference topics
Income taxes	Calculate income taxes	Income tax deadlines
	File income taxes	Addresses of tax offices

This means that the topics are related as a whole. And they will remain related, even if you update one of them by adding, changing or deleting a paragraph.

This is a pretty new concept if you’re used to writing long single documents. And it might feel awkward to have references outside and removed from the linked topics.

Advantages of relationship tables

Once you wrap your head around the idea, relationship tables have several advantages:

• Keep your topic text flexible. With such a table, you don’t lock your topic into a certain scenario as a cross-reference does. A cross-reference establishes a fixed connection – which might be irrelevant or not even available for certain users or product versions. It’s much easier to drop a topic in a relationship table where it will not appear if it doesn’t exist for certain users or products.
• Keep your references complete and up-to-date. With tables, it’s much easier to oversee the complete set of links and relationships than with cross-references inside topics. If you’ve ever tried to manually update and rephrase links to a new important topic which has replaced an obsolete topic in countless places, you will appreciate a table where you can simply add or omit any one topic.

Relationship tables are not superior to cross-references. They simply serve a different purpose. I hope this post helps you to appreciate the benefits of either type and to decide when to use which. Please leave a comment to let me know if I’ve succeeded or have been wrong or unclear somehow.

For more about converting documentation to topics, see previous posts about:

• 5 steps from legacy documentation to topics
• Wrestling with ornery topics when topics don’t quite work
• Deciding if a topic should be a concept or reference

Advertisement