DITA: 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

<topichead navtitle="Links" collection-type="family">
 <topicref href="keyref_links.dita"/>
 <topicref href="inline_links.dita"/>
 <topicref href="related_links.dita"/>
 <topicref href="relationship_tables.dita"/>
 </topichead>

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

Here's an example:

      <reltable>
      <relheader>
   <relcolspec type="concept">
   <relcolspec type="task">
   <relcolspec type="reference">
      </relheader>

      <relrow>
        <relcell>
          <topicref href="sample_concept.dita"/>
        </relcell>

        <relcell>
          <topicref href="task_example1.dita"/>
          <topicref href="task_example2.dita"/>
        </relcell>

        <relcell>
          <topicref href="referencefile.dita"/>
         </relcell>
      </relrow>
    </reltable>
   

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-links>
  <link href="http://example.org">Example.org</link>
 </related-links>

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.

Column headers

<relcolspec type="concept"/>
<relcolspec type="task"/>
<relcolspec type="reference"/> 

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 cell.

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.