Embedded topics and ditamaps

The ditamap is a powerful tool for re-using topics in different output publications. Topics can also be re-used using ditabase topics, but you should avoid this technique.

It is possible to create a document made up of one topic. For example, you may be writing a product information sheet as a reference topic type, and that's it. The sheet doesn't belong in a manual or in a collection of topics. It's a standalone topic. However, this scenario is the exception, rather than the rule.

The purpose of a ditamap is to bind a set of topics together into a collection, using topic reference (topicref) elements. The same topic can be re-used in different ditamaps defining different output publications.

There is another way in which you can collect topics together: through a ditabase topic. It's not necessarily the right way to collect topics, but it may be appropriate in some circumstances (although some DITA purists would say that it is never appropriate). The ditabase information type was designed as a means of collecting multiple topics together into one composite file.

The root node of a ditabase topic is dita. The dita element (or wrapper) allows you to nest several child topics (as siblings of each other). You can mix and match topic types in this way, such that a dita element could contain three task elements, a concept element, two topic elements, and a reference element.

If constituent topics are transcluded into the composite ditabase topic, those topics can be re-used in other composite topics. In other words, the ditabase topic can serve as an alternative to a ditamap.

You should avoid or at least minimise the technique, though. Topics embedded in other topics become difficult to re-use, and difficult to handle in other ways.

The preferred method of re-using topics is with the ditamap.