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:
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:
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:
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:
When you generate the DITA XHTML output, the result looks like this:
You could then add a style to your site like this:
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.
See also the Combining topics page in my DITA QRG.
About Tom Johnson
I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.