Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,505

Stitcher radio

follow us in feedly

Want more tech comm blogs to follow? See my Tech Comm Collection of Blogs on Feedly.

Adobe Robohelp

DITA: Nested subheadings and the concept element

May 8, 2014 • dita

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.

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 3,505

Powered by ZipRecruiter

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.