Stem topic

A stem topic is not a defined topic type, but a "special version" of a standard concept topic. A stem topic contains only a heading (<title>). It is used to establish the title of a chapter.

On this page

• Definition
• Basic characteristics
• Purpose and use

Definition

The term "stem topic" is not a standard designation that you find in the Oasis documentation. Nevertheless, it is a topic that is both useful an necessary. Different DITA users have different names for it.

Basic characteristics

A stem topic contains a <title>, perhaps a <shortdesc>, and possibly index terms. A stem topic is used to place a heading in front of a number of topics at an underlying level.

Purpose and use

To understand the purpose of a stem topic, we have to look at the structure we build up in a map. A bookmap is used here:

Here, the first chapter contains five sections in a flat structure, as follows:

1. Chapter 1
   1. Section 1
   2. Section 2
   3. Section 3
   4. Section 4
   5. Section 5

The five sections each have their own title and contain more or less text. These are placed under chapter 1. This chapter must also have a title, but no text . Since <chapter> must be a topic, we create a stem topic that only contains the desired title. In this way, we get a structure that looks like this, for example:

1. Introduction
   1. About this publication
   2. Product description
   3. System diagram
   4. Main parts
   5. Help and support

To create a stem topic for "Introduction", these DITA elements are used::

The example in the illustration shows how a stem topic only contains the title Operating procedures.

Naturally, a stem topic can contain more than just the title. How much information such a voice should contain before it becomes a "regular topic" must be made a rule in the writing team. In my team, we have decided that a stem topic should only contain a title (<title>), but that it is allowed to add a generic introduction (<shortdesc>). Whether it is permissible to enter indexes must be agreed upon in the writing team. Here you have to make rules.

The advantage of creating rules for this is that very many titles are used in very many books. This means that a stem topic containing, for example, the title Introduction can be reused in countless publications. Such reuse means that titles (and preferably also structure) are consistent in all publications where the stem topic is reused. It is also only necessary to translate it once. By reusing stem topics, it is even easier to establish links between the various parts of the publication.

Related tasks

Creating a new DITA topic from a template

Creating a new DITA topic by duplicating an existing topic

Inserting a topic into a topic map

Inserting a topic into a bookmap

All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.

The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.