Search results

DITA's output does not require separation of tasks from concepts

by Tom Johnson on Jan 5, 2014
categories: dita findability

One of the main challenges to embracing DITA is accepting the idea that tasks and concepts should be separated. However, despite the common assumption that concepts and tasks should live separately when you follow DITA, actually it's not the case. You can combine concepts and tasks in DITA's output through your ditamap. Additionally, you can even combine concepts and a single task in a "general task" dita topic.

Tasks versus concepts

Pretty much any tutorial you read about DITA starts off by defining DITA's three main topic types: concept, task, and reference. When you author DITA content, these topic types impose certain limitations about tags that are and aren't allowed.

With concepts, you cannot include the steps tags (used extensively with tasks). With tasks, you cannot include the section tag. Although you can include brief conceptual content in a task in the shortdesc, context, and prereq tags, the bulk of the conceptual material is shifted into a concept file.

This separation of tasks from concepts in the building blocks of DITA is fine, because your dita files aren't the same as your output files. In your ditamap file, which defines how each of these components is arranged in the output, you can combine concepts and tasks to your heart's content.

For example, here's a ditamap file that combines five subtasks into one article:

</p>
<p><topicref href="admin_console/rewards/managing_contests.dita" chunk="to-content"><br />
   <topicref href="admin_console/rewards/create_a_contest.dita" toc="no"/><br />
   <topicref href="admin_console/rewards/end_a_contest.dita" toc="no"/><br />
   <topicref href="admin_console/rewards/find_contest_winners.dita" toc="no"/><br />
   <topicref href="admin_console/rewards/export_contest_winners.dita" toc="no"/><br />
   <topicref href="admin_console/rewards/archive_a_contest.dita" toc="no"/><br />
 </topicref></p>
<p>

The chunk="to-content" attribute says to combine the children with the parent. The parent is denoted by the lack of a closing />. All contained topicrefs are thus included as children to this topicref, until the closing .

In the output, users will see just one file: "Managing Contests." This file probably includes some conceptual information about contests followed by 5 tasks: Create a Contest, End a Contest, Find Contest Winners, Export Contest Winners, and Archive a Contest.

Sure, my source files have 6 different DITA files, but the output is just one article.

One reason so many people mistake the architecture of the source files with the architecture of the output files is because the term "topic" tends to get used for both situations. I prefer to call the output files "articles" rather than topics. An article might consist of several topics. Each of those topics might be of several different types: concept, task, or reference.

If DITA tutorials were a bit more explicit in differentiating between source file architecture and output architecture, we wouldn't end up with so much confusion. There would be fewer DITA-authored help files that fragment information into lots of tiny files, and the user experience would improve.

Reasons to combine concepts and tasks in the output

One might ask, why not separate concepts from tasks? After all, isn't a minimalist design philosophy task-oriented, so help should mainly consist of standalone tasks? We want to get all the conceptual information out of the way so users can do the task they need, right?

In some cases, it may make sense to separate out tasks into their own articles. In other cases it might not. It all depends on the material. If it seems like the material belongs in the same article, like the example I described above, where the tasks are pretty short, then combine them. If not, if the tasks are longer and more elaborate, separate them into their own articles.

Sometimes concepts and tasks belong together.
Sometimes concepts and tasks belong together. If that's the case, combine them in the ditamap.

When you start separating some information into one article simply because it consists of conceptual paragraphs, and you put other information into another article because it's a list of steps, even though both the concept and steps go together like a pair of shoes, you end up fragmenting the help information. You force users to jump around from article to article, trying to find all the information necessary to achieve their goal. Mark Baker calls this fragmented output a frankenbook.

DITA isn't built on any kind of learning theory propounding that separating tasks from concepts in the output improves the user experience. Certainly many users are task-oriented because they're trying to perform a goal, no question. But performing that goal often requires more than starting at step one. Often the conceptual information is the information the user needs to complete a goal. More complicated processes are not often reduced to a list of steps.

In other words, an action-oriented approach doesn't mean you marginalize conceptual information, splitting it off from tasks.

A few people have written about the information fragmentation problem that DITA's separation of task, concept, and reference create. See this seminal post by Mark Baker: The Tyranny of the Terrible Troika: Rethinking Concept, Task, and Reference.

And this thought-provoking post by Ruth Haworth: Case study: DITA topic architecture. Ruth's post is particularly poignant because she gathers direct feedback about the poor user experience resulting from information fragmentation.

See also this post by Jonatan Lundin, Are users always in learning mode, as minimalism tells us?.

Also, I previously wrote a post called Does DITA encourage authors to fragment information into a million little pieces? (If you can read through all 98 comments on that post in one sitting, my hat is off to you.)

Summary

In summary, remember that there's a difference between source file architecture and output architecture. Although the concepts and tasks may be separated in the source files, they can easily be combined in the output files through the ditamap. (If DITA had a information model that prohibited combining tasks with concepts, the DITA developers wouldn't allow and validate the structure in the ditamap.)

By the way, in addition to the task, concept, and reference, there are actually several other topic types introduced with DITA 1.2. There's a glossentry type, a machinery task topic, a bookmap topic, and more.

About Tom Johnson

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.