DITA: Limitations with the chunk="to-content" attribute in relationship tables
Updated 5/11/2014.
DITA has a lot of powerful ways to combine different topics through ditamaps. Although DITA's architecture encourages a lot of little pieces of content, you can bring these pieces together into articles of more substance. By having smaller chunks of information, you have more capability for re-use into various combinations and outputs.
Here's an example of chunking. Here I have a task of changing a tire, which involves 5 topics (1 overview topic and 4 task topics).
<topicset id="topicset_changing_a_tire" chunk="to-content"
navtitle="Changing a tire" href=“changing_tire_overview.dita">
<topicref href="remove_the_tire" toc="no"/>
<topicref href="inspect_the_tube" toc="no"/>
<topicref href="insert_a_new_tube.dita" toc="no"/>
<topicref href="reinstall_the_tire.dita" toc="no"/>
</topicset>Each of the subtasks is a task topic with a list of steps. In this hypothetical example, the steps are fairly minimal. The task element allows just one set of steps per topic, which is why the content is split into multiple files. The overview topic is a concept topic. In reality, it's not more than a paragraph long. It could preface the first task topic, but then the first task topic wouldn't look like a subheading underneath the overview.
By adding the attribute chunk="to-content", the Open Toolkit will merge all of the topics to the same content. The reader will see one article.
You don't have to use topicset element for this. You could also do the following:
<topicref chunk="to-content" href="changing_tire_overview.dita">
<topicref href="remove_the_tire" toc="no"/>
<topicref href="inspect_the_tube" toc="no"/>
<topicref href="insert_a_new_tube.dita" toc="no"/>
<topicref href="reinstall_the_tire.dita" toc="no"/>
</topicref>The topicset method gives you a way of re-using the same set of topics in another map without including the whole list of topics.
Where the problems begins
The topicset content looks fine in a table of contents — it appears as a single unit of information. However, when you add the topicset in a relationship table, using the topicsetref ID, the Open Toolkit can't process it correctly. The link simply doesn't work because the Open Toolkit seems to require actual files in order to process the relationships. The topicsetref isn't a file — it's an ID that includes several files.
There are several ways to handle the issue, which I'll explore in detail. None of the workarounds really solves the problem.
Discrete little topics
One common workaround is to avoid the chunk attribute altogether and instead to just use little topics in your help. You can still group the topics in the same folder, and with a table of contents navigation, the user can jump from one topic to the next. Each page will contain a link to its parent topic, which helps avoid information fragmentation.
The problem occurs when users perform searches. If a user lands on subtask 3, "Insert a new tube," he or she might be somewhat lost. The subtask isn't meant to stand alone.
Unfortunately, I think that too many DITA help systems lean towards tiny topics. Best practices with help authoring is to provide enough information for a user to complete a real task or goal, without having to jump around the help system to find all the necessary information.
Substeps
Another workaround would be to use the substeps element. You can create substeps within with each step element, which would allow you to combine this task into one list of steps.
This might not be a bad idea, especially if you can style the substeps attractively. But in general, I prefer to put headings on each of the subtasks, and maybe even short descriptions or context below the headings. You can't insert either of these elements in a steps element.
Concept type
Another workaround would be to use the concept topic type, which allows sections. For each section, use ol and li tags for the lists. You can't use the steps element in a concept, but hopefully your HTML styles would provide a similar look and feel to both types of output.
Additionally, if you're able to put all of these subtasks into the same topic, most likely the subtasks are small. As such, using regular HTML list tags might be fine.
The problem is that this method introduces two different methods for tagging for lists, which feels inconsistent. Ideally, it would be best to stick with one way of structuring lists in instructions.
Dita topic type (composite)
You could also use a dita topic type (sometimes called ditabase), which allows any element (concept, task, reference). However, when you refer to the dita topic in the relationship table, the related links produced by the relationship table will appear after the first element (after the changing_tire_overview.dita topic, not after the last topic in the set).
Refer to the first section, hack the XSLT
Another workaround would be to refer to the first topic rather than the topicset ID in your relationship table. This technique results in the same effect as referring to a ditabase file — the relationship table appears after the first topic, not after the set of topics.
I've been told I could hack the XSLT with an override to get the functionality I want — putting the relationship tables at the end of the topics. I'm not sure whether this hack would be involved or trivial, and what other impacts it might have on the way related links works. Apparently this is not a feature many others have been complaining about (though this perplexes me).
Don't use relationship tables
Another strategy might be to avoid using relationship tables for links altogether, and instead just use the more manual related-links element.
Relationship tables require all your information to be in DITA anyway, rather than linking to outside resources. If your related links have a mix of internal and external resources, it might be easier to manage all links manually via related-links.
The problem is that DITA gets a lot of efficiency in its linking model through relationship tables. Not using them sacrifices significant functionality.
Chunk by-document instead of to-content
There are myriad other values for the chunk attribute. (Take a look at the OASIS explanation of chunking here. One of the alternatives is chunk="by-document". This produces an interesting result. Instead of merging the other files into the same unit, the other files are nested like child pages in the document. This creates another layer for the user to drill into.
Using by-document isn't a bad solution, but again, searches for a keyword might take a user to this little piece of information rather than the whole unit. Only by back-navigating through breadcrumbs or a table of contents hierarchy will the user be able to trace back to find the whole topicset.
Nest task elements within task elements
Instead of creating separate task files, you could nest tasks within tasks to bring all of this information into the same topic. Here's an example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="task_0">
<title>Fixing a flat tire</title>
<shortdesc></shortdesc>
<taskbody>
<context>
<p>This is an overview about the task of fixing a flat tire...</p>
</context>
</taskbody>
<task id="task_1">
<title>Remove the tire</title>
<shortdesc/>
<taskbody>
<context>
<p>Context for the current task</p>
</context>
<steps>
<step>
<cmd>Task step.</cmd>
</step>
</steps>
</taskbody>
</task>
<task id="task_2">
<title>Inspect the tire</title>
<shortdesc/>
<taskbody>
<context>
<p>Context for the current task</p>
</context>
<steps>
<step>
<cmd>Task step.</cmd>
</step>
</steps>
</taskbody>
</task>
<task id="task_3">
<title>Insert a new tube</title>
<shortdesc/>
<taskbody>
<context>
<p>Context for the current task</p>
</context>
<steps>
<step>
<cmd>Task step.</cmd>
</step>
</steps>
</taskbody>
</task>
<task id="task_4">
<title>Reinstall the tire</title>
<shortdesc/>
<taskbody>
<context>
<p>Context for the current task</p>
</context>
<steps>
<step>
<cmd>Task step.</cmd>
</step>
</steps>
</taskbody>
</task>
</task>However, when you include the file in a relationship table, the related link still appears right below the first task element, like this:
Conclusion
I have asked quite a few people for solutions to this problem, including Oxygen's forum, the Yahoo DITA users group, and DITA consultants. I hoped that I was simply misunderstanding the right chunking configuration, but no, this appears to be a limitation of DITA.
A while ago I wrote a really controversial post on called Does DITA Encourage Authors to Fragment Information into a Million Little Pieces?. Many experts chimed in to reassure me that the ditamap was where you glued them all together in the arrangement you want. And indeed that is the case with a table of contents navigation — just not with relationship tables.
This problems seems to have cut right to the heart of why so many DITA help files are fully of tiny topics. You really can't get two sets of steps in the same topic while also embracing relationship tables.
I'm surprised at how sparse information was about the limitations of using chunk="to-content" with relationship tables. It suggests that most people aren't running into this problem, most likely because either (a) they aren't using relationship tables or (b) they aren't using the chunk attribute.
I am curious to learn what techniques you're using to merge smaller units of information into more substantial articles while also using relationship tables.
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.