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:

Advertisements

6 Responses

  1. Good summary, Kai. But that “web of dependencies” is such a problem, particularly when a lot of people are collaborating on a lot of topics, that I tell people to use relationship tables for every topic-to-topic link. Otherwise, as the content evolves over time, broken (or inappropriate) links are inevitable.

    I use ordinary cross-references only for intra-topic links, for example “…the value you selected in step 2.”

    True, the relationship table puts all of the links at the bottom of the topic. But writers can call out the other topics in the text using — or better yet, simply by describing the other topics’ contents (example: “before doing this task, you must configure the modem” with a link to Configuring the modem at the bottom). Readers will easily find the list of links at the bottom — or, if necessary, the writer can direct them there.

    • Thanks, Larry. It’s good to hear an experienced voice from the trenches, and I’ll keep your advice in mind. I hope we have two factors work in our favor and mitigate the mess of the dependencies web: Most concept and task topics that I expect to tend towards cross-references are assigned to one domain and its writer. And since we use MadCap’s MadPak, we have a chance to find broken links with Analyzer before publication – though I don’t think it’ll help us with inappropriate links.

  2. Just a brief comment to the advantages of cross-references: actually DITA offers you the possibility to achieve these two points also with relationship tables. You can define sequences of topics and also if one topic is pre-requiste to the other – just look out for the collection-type=”sequence” (I made a 3-part-series on linking in DITA 2 years ago -> http://www.redakteuse.de/?p=316). So I don’t see any advantages to cross-references at all, except for the example Larry mentioned.

    • Thanks, Marijana, for anyother very interesting take! I’ll have to investigate whether our particular setup with a half-way DITA information model and MadCap Flare as our tool supports the sequence collection type. Or maybe we can just model it using the relationship tables which I believe are customizable in Flare.

  3. This is an old thread (written 2012, and it’s now 2016) but still relevant. Here’s another contrast between cross-references and relationship tables: one technique is manual and the other is automatic.

    Cross references are manual in the sense that a writer decides when they’re needed, and creates the link. Relationship tables are automatic in the sense that the writing platform displays whatever links are available.

    This is particularly important for single-source documentation that contains conditions. Imagine two similar products, AA and BB. They share the same overview and some of the same features. A writer creates a cross reference from the overview to a feature that is conditioned for product AA. When building product BB, the feature topic disappears and the link in the overview breaks (if it doesn’t have a matching condition).

    If a topic in a relationship table disappears from a build, nothing breaks.

    • Thanks, Peter, for taking the time to improve an old, but (I hope) still valid post. Yes, relationship tables are indeed automatic. That’s what I meant by “… a topic in a relationship table … will not appear if it doesn’t exist for certain users or products.” But you put it so much more succinctly and more clearly! 🙂 Thanks, Kai.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: