Stem topics

Rather than manually creating links from parent topics to child topics, and arranging the links into a formatted table, you should take advantage of the ability to automatically generate links and descriptions to topics subordinate in the hierarchy. A parent stem topic in the DITA source can become an important introductory topic in the deliverable document.

A stem topic is a short topic that contains very little content, instead providing pointers (cross-reference links) to related information. Stem topics are used as navigation aids for online documents.

Stem topics should not contain descriptions of the related topics; instead, the publishing process should be used to automatically insert links and short descriptions to the related topics. Stem topics are typically parent topics in a Table of Contents hierarchy, where the related topics are children of the (stem) parent. Avoiding content in stem topics reduces the amount of redundant writing (writing a short description twice, once in the stem topic and once in the target child topic), and avoids embedded links that reduce re-usability (as the stem topic with an embedded link can only be used if the linked topic is part of the same collection).

For example, the following stem topic is not desirable, as it includes content and embedded links.

Example of stem topic with embedded links and table formatting

Example of stem topic with embedded links and table formatting

You should instead use relationships in the ditamap to automatically generate links to the child topics, and automatically place the short descriptions of those child topics. This approach would result in the following deliverable document.

Example of stem topic with generated links to subordinate topics

Example of stem topic with generated links

Although it may not have the same aesthetic appeal as the manually created stem topic, the benefits of re-usability and efficiency outweigh the look-and-feel.