Add topicrefs to the correct column

When adding topicrefs to a row in a reltable, make sure that you add the topicref to the appropriate column based on the topic type. For example, all topicrefs to concept topics should be added to the Concept row. Structure topic references should be added to the Structure column.

Including multiple topics of the same type in a row

You can include multiple topics of the same type in a row of a relationship table and create links between those topics. To do this, enclose the topicrefs in a topicgroup element and set the collection-type attribute to family for that topicgroup.

Avoid xrefs to topics

Every link you need to create to topics should be defined in a relationship table rather than as an xref in a topic, if possible. There are issues with using xrefs to create links to topic, especially with reused content:

• If you own common content that is reused, avoid using cross-references to topics wherever you can. When you use xrefs to topics and someone reuses your content, if they aren’t reusing the topic that’s the target of the xref, they’ll end up with a broken link in their output. It also causes potential problems related to localization, which are explained below.

• If you reuse a topic that contains an embedded xref and the target topic is not included in your deliverable, your output will contain a broken link. If you’re reusing topics that include xrefs to topics, request that the content owner move the xref to a relationship table link instead.

• When you reuse content that contains embedded xrefs, that creates a dependency on the topics that are the target of the xrefs. If the content is localized, all content that is referenced is included in the package sent for translation. So if you’re reusing content that includes xrefs to other topics, those other topics are included in the package for localization, even if you are only reusing an element in that topic that does not include the xref. This increases translation costs.

• If you create relationships between topics, you do not need to include a text reference to that topic.

There are some limited cases where it's better to embed the xref directly in the topic content. For example, in an installation checklist or when the context of the link would be completely lost by not embedding it in the text.

It’s not an issue to include xrefs to external targets, such as Web sites.

All topics included in the relationship table must be included in the map hierarchy

A known current limitation is that links to topics external to the map cannot be resolved. So, if you have a reference in a relationship table that is not part of the output you’re producing, the link won’t be resolved. So you must include any topics that you want to link to in the hierarchy of the map. If you do not want the topic to be included in the PDF output, set the print attribute to no. If you do not want the topic included in the table of contents of the HTML output, set the toc attribute to no.

Text references in content to topics participating in relationship tables

Don’t include text references to a topic that you’re linking to via a relationship table unless necessary. Benefits of using reltables include the flexibility of where you use the topic and minimizing distractions for the reader. When you add a reference in the topic text, you create a dependency, even if the dependency is not a physical one. And it’s queue to the reader that they should stop reading this topic and go to the one that’s being referenced. If you do feel that a text reference is important, tag the text reference with the <q> element.

Include information about relationship table links in topics

It’s a really good practice to include an XML comment at the top of topics to indicate any topics they have relationship table links to. This is especially important for topics that are reused so that writers reusing that topic can see the topics the writer is linking to in a relationship table and can set up the same relationships in their maps.

One relationship link type that does not work

Relationship table links do not work from topics that are the first or only topic in a chapter or appendix.