The <section> element is a great example of why DITA requires us to think and write differently. In an unstructured environment, a section can mean whatever you want it to mean – it is a handy way of describing the chunks of a document without really defining what those chunks are.

For writers starting to use DITA, a common mistake is to use the <section> element in the same way. However, section elements cannot be nested in each other, so authors looking for some hierarchical organisation within a DITA topic quickly become frustrated by the lack of flexibility. Section titles also do not appear in the table of contents or other navigation. Using Sections may also place additional cognitive load on the author because it requires them to remember when a section is required and when a different element should be used.

<section> is one of several DITA elements that provide ‘a base for specialization’ – meaning they are vanilla versions of content structures that you can make specific to your requirements, and not necessarily useful as-is. For example, the <example>, result>, and <postreq>, elements are all specialisations of Section within the current DITA specification. Sections are designed to be invariant topic elements that aren’t in the navigational hierarchy and don’t need nesting. You may find that sections work well with content where topics have the same consistent sections – for example in a piece of API document every topic may include the same sections such as: Authentication, Arguments, Example Response and Error Codes. Repeating these subheadings endlessly in the TOC is not necessarily helpful, and each topic always has the same subheadings with no variation.

If sections aren’t a suitable choice, what are the alternatives? It may be that you decide to break up your content into individual topics and use the map to arrange them hierarchically, perhaps using the @chunk attribute to stick them together in semantically meaningful units. Another approach, is to nest topics within topics. While we’re often told that one topic has to represent a single idea, it’s not inherently bad to nest topics within topics if that is a natural chunk size. The DITA for Publishers specialisation makes use of that principle, while also incorporating semantic names for subtopics such as part, article, subsection and so on.

There are many ways to achieve a similar output – the decision on which is best needs to be based on output requirements, reuse potential, localization requirements and author experience.