Nest DITA topics under a topic or under a topichead?

nesting DITA maps and DITA topics

For the red-footed booby (Sula sula) nesting comes naturally. For DITA projects, nesting topics and maps requires some forethought and planning

When you have a collection of DITA topics to nest, or individual DITA topics to next, you have a lot of choices. Often, too many choices. In a ditamap, you can nest DITA topics under a topic, <topichead> or <topicgroup>. In a bookmap, you can nest DITA topics or a ditamap under the <part> or <chapter> element.

The best practice, in general, is to group related topics in a DITA map, and then to nest those topics by referencing the ditamap from a parent bookmap or regular map. This allows easy reuse of the  collection of topics, and allows editing of the DITA map in parallel to editing of the bookmap. Click here to learn more about when to use bookmaps and when to use regular ditamaps.

When should you nest DITA topics?

Nested task topics are especially useful when a procedure divides into individual tasks.  You can nest the subtasks under a concept topic or under a task topic.

Where should you nest DITA topics in a ditamap – under <topic> or under <topichead>?

In a standard ditamap, you can nest topics under a parent topic or under<topichead> or <topicgroup>. Using a parent topic rather than a <topichead> element enables you to easily add a short description or context information to the collection to topics.

Tip for when you nest DITA topics

If the subtasks need to performed in a particular order, set the collection-type attribute for the parent topic to sequence.

Your next steps

Get help right now from the DITA gurus at Method M.