DITA: Nested subheadings and the concept element
5/11/2014 update: I updated this post with more accurate information, particularly about nesting concepts within concepts.
When you're writing concept topics, at times you may need a third level subheading. Usually the article title is the first level, your main subsections are your second level, and sections within the subsections are third levels. These correspond with h1, h2, and h3 on a typical web page.
For example, suppose you're writing a document on Testing Procedures. There are 3 areas to test: Widgets, Gizmos, and Thingees. Each area must be tested for (1) correct configuration, (2) performance, (3) scalability, and (4) browser compatibility. Your document outline looks like this:
Testing process Widgets - Correct configuration - Performance - Scalability - Browser compatibility Gizmos - Correct configuration - Performance - Scalability - Browser compatibility Thingees - Correct configuration - Performance - Scalability - Browser compatibility
Assume that each of these sections is fairly short, and the document overall isn't more than 800 words.
You have three main options for handling this type of structure.
Approach #1: Separate topics
You could create three separate concept topics, one for Widgets, one for Gizmos, and one for Thingees.
Then through your DITA map, you could build the content into a group, like this:
<topichead navtitle="Testing process">
<topicref href="widgets.dita"/>
<topicref href="gizmos.dita"/>
<topicref href="thingees.dita"/>
</topichead>By breaking up the document, you can more easily re-use the different parts in different areas of your documentation. For example, if you have an audience that is only interested in thingees, you could more easily reuse thingees in a ditamap built just for this audience.
One advantage of breaking content down into small chunks like this is the information becomes easier to manage. It's no fun working in a really long document that has multiple heading hierarchies. Documents with multiple heading hierarchies tend to get quite long and unwieldy. Splitting up your content ensures that you keep things relatively short and simple.
The downside of the small units model is that it's not so easy to glue everything back together. If you want to get that same long document, you could use the chunk="to-content" attribute on the first topic. Then everything would merge into one article. However, using this attribute gets you into problems with relationship tables, as I explained in my previous post (DITA: Limitations with the chunk=”to-content” attribute in relationship tables).
The best approach would be to create an overview topic that acts as a parent (which means all child pages will be embedded as links on the parent), avoid the chunk attribute, and only use the overview parent in the relationship table.
Approach #2: Nested concepts
Another approach to writing for heading level 3 sections is to nest concept elements within concept elements. You can nest one concept tag within another, like this:
<concept id="concept_1">
<title>Concept title</title>
<conbody>
<p>Concept definition.</p>
</conbody>
<concept id="concept_2">
<title>Concept title</title>
<conbody>
<p>Concept definition.</p>
</conbody>
</concept>
</concept>When you output the content, the heading levels for the nested concept will be one level down.
Here's what our content would look like in our example scenario:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="concept_0">
<title>Initial setup</title>
<conbody>
<p>To configure this system, you need to test your widgets, gizmos, and thingees.</p>
</conbody>
<concept id="concept_1">
<title>Widget testing </title>
<conbody>
<p>Here's some info about testing widgets.</p>
<section><title>Correct configuration</title>
<p>Here's how you test for correct configuration.</p>
</section>
<section><title>Performance</title>
<p>Here's how you test for performance.</p>
</section>
<section><title>Scalability</title>
<p>Here's how you test for scalability.</p>
</section>
<section><title>Browser compatibility</title>
<p>Here's how you test for browser compatibility.</p>
</section>
</conbody>
</concept>
<concept id="concept_2">
<title>Gizmo testing </title>
<conbody>
<p>Here's some info about testing gizmos.</p>
<section><title>Correct configuration</title>
<p>Here's how you test for correct configuration.</p>
</section>
<section><title>Performance</title>
<p>Here's how you test for performance.</p>
</section>
<section><title>Scalability</title>
<p>Here's how you test for scalability.</p>
</section>
<section><title>Browser compatibility</title>
<p>Here's how you test for browser compatibility.</p>
</section>
</conbody>
</concept>
<concept id="concept_3">
<title>Thingee testing </title>
<conbody>
<p>Here's some info about testing thingees.</p>
<section><title>Correct configuration</title>
<p>Here's how you test for correct configuration.</p>
</section>
<section><title>Performance</title>
<p>Here's how you test for performance.</p>
</section>
<section><title>Scalability</title>
<p>Here's how you test for scalability.</p>
</section>
<section><title>Browser compatibility</title>
<p>Here's how you test for browser compatibility.</p>
</section>
</conbody>
</concept>
</concept>I like this method, though I wouldn't recommend nesting any more levels.
Approach #3: Use an output class disguised as an h3
You could also add an outputclass attribute to a p tag and use it for your nested subheading. For example, you could do the following for your third level:
<p outputclass="nestedsubhead">Performance</p>When you generate the DITA XHTML output, the result looks like this:
<p class="p nestedsubhead"/>Performance</p>You could then add a style to your site like this:
p.nestedsubhead {font-family: Georgia; font-size:18px; font-color: blue;}The result would look just like a heading level 3, but without the semantic significance of being a heading level.
No doubt this third method is a simple hack that is probably frowned upon, but it would be a quick way to achieve the same nested subheading result. The only problem is in making outlines for your pages. If you implement a table of contents plugin on your web page, usually the plugin will look for the heading levels and render and outline accordingly. If your third levels are simply a class, they won't appear in the outline.
Related links
See also the Combining topics page in my DITA QRG.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.