Woes of conditional text and topichead elements (DITA best practices)

by Tom Johnson on Aug 10, 2014
categories: dita

When authoring in DITA, there are a couple of best (or worst) practices that I wasn't aware of. The first is with conditional text; the second is with topichead elements:

Cautions with conditional text

Noz Urbina has written two excellent articles about the dangers of going overboard with conditional text.

• When Conditional Content Goes Wild: 4 Top Tips for Avoiding Pain – Part 1
• When Conditional Content Goes Wild – Part 2: Securing Support and Making Deep Changes

Noz encourages caution when adding too many conditions to topics. He shows the potential complexity with this clever diagram:

With such complex conditional logic, the content becomes nearly impossible to edit.

Noz also talks about the opposite approach. Rather than conditionalizing content, you can transclude it (conref it) from another source:

Although transclusion can simplify re-use somewhat, transclusion can also become paralyzingly complicated as well. If you want to edit a specific chunk that you're reusing in 5 different topics, you need to know how your edits of that chunk will affect its context in each topic.

When you have just a few conditions or transclusions with your content, there's no problem. But when you suddenly realize that editing the topic is requiring an immense amount of concentration and careful analysis because you've got too many conditions or transclusions to sort out in your mind, you have to consider whether simply copying and pasting is more efficient.

In converting a recent set of help content to DITA, the original content was heavily transcluded, to the extent that most of the articles were simply blocks of re-used content. I spent days tracking down and identifying the outputs where each piece was transcluded and essentially copied the transcluded content into one aggregate document with various condition tag notes. (It was impossible to edit a simple topic because I didn't know where all the transclusions were embedded. The re-used paragraphs were also somewhat hard to find. Such is the case when you author in Confluence.)

As I structured the content with DITA, at times I went overboard with conditional tags and ran into the same situation -- the various conditions applied to many topics had so many spinoffs with different products, programming languages, and audiences that it also was nearly impossible to edit.

I don't have a magic bullet solution to getting around this except to offer this advice: when the reuse gets complicated, choose the method that saves you the most time. This may mean using transclusions instead of conditional text. It may mean breaking the content into smaller topics. It may mean having some redundant content that you copy and paste across topics. But just don't let your content become so complicated that it becomes uneditable.

Now let's move to another DITA worst practice: the topichead element.

Topichead elements

I first ran into the idea that topichead elements were a no-no while reading Tony Self's DITA Best Practices, which is (interestingly) integrated into Oxygen's webhelp here: The topichead element.

Tony writes:

There are two main reasons why topichead elements should be avoided.

The first is that it conflicts with the notion of the separation of content and form, and the separation of data and metadata. All content (data) in a document should reside in the topics, not in the map. The ditamap should only contain metadata. If you use topichead as an alternative to a title-only topic, you are effectively placing non-reusable content, or data, in the ditamap.

The second reason is more practical. If you are transforming a ditamap to a hypertext output format with a TOC, such as to Eclipse Help, the topichead elements will be transformed to unlinked parent nodes in the TOC. When the user clicks on such a node, the content pane will not display an associated topic, as it will for other nodes in the TOC. This inconsistency appears to the user to be an error. The unlinked node in the TOC will also cause inconsistencies or malfunctions in the way breadcrumbs function, and the way sequences (previous and next topic links) function.

If you're not familiar with topichead elements, they essentially let you create folder titles and group together your topics in your table of contents in your map file. Here's an example:

<br />
 <topichead navtitle="Resources"><br />
  <topicref href="sample1.dita"/><br />
  <topicref href="sample2.dita"/><br />
  <topicref href="sample3.dita"/><br />
 </topicgroup><br />

At first I wasn't sure of Tony's recommendation, so I asked the Yahoo DITA Group whether it was generally accepted that topichead elements should be avoided. Several people endorsed Tony's recommendation.

Even apart from the usability issues, I think there are other good reasons for not using topichead elements. Most of the time, when you have a folder, you want to provide an overview of the folder (Flare had mini-TOCs partly for this reason). Writing this topic is usually tedious because it's so high level. You're mostly giving a summary of each of the topics within that folder.

Here's where DITA's efficiency shines through. Create a blank concept topic called something like toc_resources.dita. Make it the parent topic for all other topics in the folder, like this:

<br />
<topicref href="resources.dita"><br />
  <topicref href="simple1.dita"/><br />
  <topicref href="simple2.dita"/><br />
  <topicref href="simple3.dita"/><br />
 </topicref><br />

Make sure each of your child topics has a shortdesc element. Now after you generate your output, when a user clicks the folder, the overview topic will appear with each of the subtopics embedded on the parent page (like a mini-TOC), and their short descriptions right next to them. This is a brilliant way of providing a summary overview of the folder.

In short, ditch the topichead and just put a blank overview topic as the parent topic for each folder. You won't have to bother writing a superfluous high-level overview topic, and you avoid the usability issues with unlinked folders in the UI.

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.