DITA: Relationship tables
A relationship table is an actual table grid that defines the way topics link to each other. You add links to topics in the table's rows and columns. Topics in the same row link to each other. When you output your help, if some of the topics aren't included in the output, they are intelligently not included in the relationship table, so your links don't break.
There are quite a few options for how you can define the linking relationships, but here's the easiest way to implement relationship tables.
Wait until the end to create the links
First, wait until you're mostly done with your help content before you start creating link relationships. You may be changing link names as you write and organize files, and it doesn't make sense to try to establish linking relationships to content that is still in constant flux.
Link related topics through your topicheads directly
topicheadarea (which groups topics together), add the
collection-typeattribute with a value of
family, like this:
All of the topics in this group will link to each other via related links at the bottom (just like with relationship tables). You don't have to actually create a relationship table at all with this method. In almost all cases, you want to link these groups of files to each other.
Linking topics that appear in different groups
- Topics in the same row link to each other.
- Topics in the same cell do not link to each other.
Here's an example:
It may make more sense to actually show the table in its display form:
In this relationship table, sample_concept.dita will have links to task_example1.dita, task_example2.dita, and referencefile.dita because they're in the same row.
However, task_example1.dita and task_example2.dita will not have links to each other because they're in the same cell.
If you want topics in the same cell to link to each other, add the attribute
collection-type="family" to the
relcell element that
contains the topics you want to link to each other.
Linking to external resources
Now let's say some topics link to some external files on the web. For example, suppose you
want the inline_links.dita topic to link to a topic called http://example.org. You could
manage these external resource links in the relationship table, but it's easier to manage
them in a
related links section of the topic itself. The related links will
be combined with the relationship table links at runtime.
related-linkselement in a topic, add it after the
This kind of link is useful as a list of relevant resources about the topic. You don't need to manage these links in the relationship table because, as a web resource, you don't need to worry about the topic not being available in the output.
typeattribute to the
relcolspecelement, like this:
However, I don't think it's wise to separate related links into these different topic types, since many times readers don't clearly distinguish topic types frome ach other, and sometimes concepts are somewhat task-like anyway. If your concepts have lite list formatting in them (using the ol element), the distinction between tasks and concepts may be more fuzzy.
In fact, if you remove the column names, there isn't much reason to separate out the topics
into separate columns. You could instead just group all the topics you want to relate to
each other in the same cell and add
collection-type="family" for that
Working with relationship tables
Probably the easiest way to work with relationship tables in Oxygen is to insert the relationship table code into the bottom of your map file in the Text view (or make sure your cursor is in a valid place in the map file and click the Insert Relationship Table button in the Author view). Then switch to the Author view.
Right-click the map file header tab and select Open in DITA Maps Manager View. Drag the
topics from the maps manager view into the cells you want. Remember, if you've already added
collection-type="family" to the groups in your map, then you only need to
relate those topics that fall outside of the existing groups.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.