How to organize a bookmap: nesting under the element

How you organize a bookmap will affect how easy or difficult it will be for you to maintain and update your content. Should you nest a DITA map under the <chapter> element in a bookmap, or should you nest topics directly under the <chapter> element?

Referencing a DITA map from the <chapter> element:

  • Enables easy reuse of the collection of topics in the chapter.
  • Facilitates editing of the DITA map for the chapter in parallel to editing of the bookmap.

Example where the <chapter> element references a DITA map

<chapter href="intro.ditamap" format="ditamap"/>

Even when a <chapter> references topics directly, those topics can reference nested subtopics

<chapter href="intro.dita">
 <topicref href="caring.dita"/>
 <topicref href="feeding.dita"/>
</chapter>
<chapter href="setup.dita">
 <topicref href="prereq.dita"/>
 <topicref href="download.dita"/>
</chapter>

What is the best way to organize a bookmap?

Bottom line: In the <chapter> element of a bookmap, should you refer to a specific topic or to a DITA map? In most cases, our vote is squarely on the side of referencing a DITA map.

For more information about the <chapter> element in a bookmap, and more code examples, click here to get details from the DITA spec. If you need more help, please feel free to reach out to us today!