DITA: Limitations with the chunk="to-content" attribute in relationship tables
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).
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:
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
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.
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.
Another workaround would be to use the concept topic type, which allows sections. For each section, use
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
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
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.
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:
However, when you include the file in a relationship table, the related link still appears right below the first task element, like this:
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
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 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.