Does DITA Encourage Authors to Fragment Information into a Million Little Pieces?
For an updated post on this topic, see DITA's output does not require you to separate tasks from concepts.
I'm currently exploring the possibility of authoring content in DITA (using a tool such as easyDITA), publishing to an HTML web help output (through the DITA Open Toolkit), and then importing the output into Drupal (through some Python scripts someone has created).
This sounds like a good workflow to me, but I've kind of run into a little problem. I want to nest some tasks into larger topics rather than having the tasks stand alone as their own TOC entries. Reason being, if every task has to stand alone in the TOC, I'll end up with a TOC that looks unnecessarily long and intimidating to users.
For example, let's say one topic in my help content looks like this:
Configuring Widgets
- About widgets
- Create a widget
- Drag a widget in place
- Change the widget's settings
- Remove a widget
- Restore deleted widgets
The word count of this topic overall, even with all of these sections and subtasks, is only about 600 words (each of the tasks is light). I could make each subtask here its own TOC entry, but then my help would start to look really long. Imagine if I have 10 topics, each similar to this one. This means my TOC would end up being about 60 entries rather than just 10.
Have you ever visited a website that has 60 navigation options at the first level? Unless it's a massive news site, you don't expect to be inundated like this with navigation choices.
What I want to do is merge some child tasks into a parent topic with the HTML web help output.
The Chunking Attribute
I asked a friend how to accomplish this, and he mentioned that there's a Chunking attribute in DITA that allows you to nest subtopics. Here's the Oasis explanation of how you nest topics:
The "to-content" token indicates that the selection should be rendered as a new chunk of content.
When specified on a topicref or topicref specialization, this means that the topics selected by this topicref and its children will be rendered as a single chunk of content.
Here's what the dita map would look like with child1 and child2 nested under parent1.
<br />
<map chunk="to-content"><br />
<topicref href="parent1.dita"><br />
<topicref href="child1.dita"/><br />
<topicref href="child2.dita"/><br />
</topicref><br />
</map><br />
Adding the chunk attribute to the map as a whole nests every child topic into one massive file. More commonly, you would add the chunk attribute to a specific topicref and then hide the children topicrefs from the table of contents, like this:
</p>
<p><topicref href="admin_console/rewards/parent1.dita" chunk="to-content"><br />
<topicref href="admin_console/rewards/child1.dita" toc="no"/><br />
<topicref href="admin_console/rewards/child2.dita" toc="no"/><br />
</topicref><br />
Child1 and child2 topics would appear in the parent1 topic and be hidden from the toc.
It doesn't seem too difficult to manage nesting via the ditamap. I author the tasks as standalone tasks but then create a more sophisticated ditamap that contains instructions on which child topics to pull into parent topics.
I'm glad DITA allows chunking, though the extra work seems a bit of a hassle. I'll end up with a lot more files to manage and will have to edit the ditamap more. Still, this method provides some more flexibility.
DITA Best Practices with Chunking?
The method for chunking has led me to consider what DITA's best practices are for chunking. I'm not a DITA expert by any means, but my guess is that DITA provides a semantic structure for content without being too explicit about how to assemble the content. The DITA specification doesn't say when you should chunk and when you shouldn't.
However, I think many DITA users extrapolate that because each task, concept, and reference is a standalone file, then it should also be its own file in the table of contents (maintaining a 1:1 ratio). The result? With each task as its own TOC entry, the TOC looks like a gargantuan list.
I'm not sure how widespread the 1:1 ratio idea is. But here's a rather lengthy excerpt on principles for writing tasks from DITA Best Practices, by Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt. There's no mention about ever chunking/merging subtasks into a larger task.
Separate Task Information from Conceptual or Reference Information
Separate tasks from long conceptual or reference information so that tasks are short, retrievable, and reusable. If you overload a task topic with too much conceptual or reference information, expert users get frustrated because they must wade through information that they might already understand.
Also, ensure that a task isn't buried in paragraphs of conceptual or reference information. Users won't expect to find a task buried in a table of reference material. And they'll probably be upset that they spent so much time digging through information that they didn't need in order to find that one specific task.
Write One Procedure per Topic
Write only one procedure per task topic so that you can more easily manage, organize, and reuse these topics and so that your users can find specific tasks when they need them. For example, don't combine the tasks for installing and uninstalling software in a single topic. Users typically won't need both of these procedures at the same time.
Also, adding more than one task per topic makes those secondary procedures harder to find. When you transform the DITA topics to an output format such as HTML, you'll see only the title of the first procedure in the table of contents.
Create Subtasks to Organize Long Procedures
Procedures that are more than 10 steps can be difficult to follow, especially if some of the steps are complex or have many substeps. Instead of creating one long procedure in a single topic, break it up into several shorter task topics. You can then assemble those task topics into a logical order that helps users to finish the entire procedure.
To create a set of task topics, start by creating a parent topic, or supertask, that describes the overall task flow. Then, nest the child task topics under the supertask in a logical order. The output will show users what tasks they need to follow and in what order those tasks must be completed.
For example, to describe how to install a database system for a financial services business, you'd need a dozen or more task topics. With DITA, you can organize and link those task topics so that users see a clear sequence of tasks. You wouldn't want to create a single task topic with 100 steps. Think of your poor users!
The following example divides the task of setting up a nuclear fusion power source for an espresso machine into three separate task topics:
Gather permits
Identify a nuclear reactor to connect to
Prepare your home for nuclear power
To organize these tasks, you can create a supertask topic called “Prepare to install Exprezzoh 9000N” and nest the subtask topics under that topic, as in Figure 2.1. When the DITA files are transformed to HTML, you get the following output.
Figure 2.1. The HTML output of a sequence of task topics.
By dividing long procedures this way, your users aren't overwhelmed, and they can see the overall sequence of tasks. You can also more easily reuse these shorter task topics elsewhere in your information set if necessary. (See DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Video Enhanced Edition, by y: Laura Bellamy; Michelle Carey; Jenifer Schlotfeldt. Chapter 2. Task Topics.)
The authors' intentions are noble: they want to enable users to go straight to the task without being burdened by so much non-essential information. They might say, Let users who want explanations follow links to concepts. Let's give the user just what he or she wants: step 1, 2, and 3 as quickly as possible, and so on.
This approach might make perfect sense if each task and concept is somewhat weighty. But what happens when the tasks and concepts are really brief? Then you end up with a fragmented information experience, with information that would normally be grouped together instead scattered all about.
The authors also assume the user has correctly landed on the task he or she wants to perform. But that's rarely the case. Usually the user wants information about configuring widgets but lands on a topic about creating widgets. Or she lands on deleting widgets when she wants information about dragging widgets.
Is it really better to require the user to jump around in your help system, bouncing from topic to topic like a lost tourist asking for directions from a dozen different people who don't have the right information? Why not give the user the complete information about a topic on a single topic page?
An Example
Here's an example of what I'm talking about when I say fragmenting user help into a lot of separate topics can result in a poor user experience.
In my trial of easyDITA, I'm really impressed by the platform and its functionality. It really does seem to make DITA easy. And the interface is attractive and intuitive. But in the help documentation for easyDITA, the way the content is a bit fragmented makes me wonder about using DITA itself. For example, take a look at the DITA Maps topic. Then jump down to the Topic Group and Topic Head topics.
Each of these topics is no more than a paragraph, and one of the topics is just one sentence long. Yep, that's right. Here's the full content for Topic Groups:
A Topic Group is simply a Topic Head without a title.
These conceptual topics are in a completely different location from The easyDITA Map Editor book, which contains topics for Adding Topic Groups and Adding Topic Heads.
By splitting each task and concept into its own file and TOC entry, the result is a somewhat scattered organization. You end up with a top-heavy TOC organization. The reader must rely extensively on the TOC to locate information.
I don't mean to pick on easyDITA. Many DITA-produced help files follow a similar pattern of information fragmentation. Take a look at http://ditainfo.info/ditainfo. As I navigate the topics, I feel as if each page is unnecessarily short. I have to rely heavily on the TOC to navigate my way around. Often I want more substantial information grouped together on the same page.
Although I'm thrilled that a standard markup for help content has gotten so much traction, I can also see why DITA still has so much resistance. When people follow the 1:1 file per TOC entry ratio, DITA-based organization looks nothing like the organization on a typical website.
A typical web page simply has more content on each page. I'm not sure how much more, but few pages have just one paragraph or one sentence. A topic is more like a Wikipedia page, which usually contains several sections.
How Long Should a Topic Be?
The discussion about chunking prompts questions about topic length. How long should a topic be? Here's a good way to measure length: A good topic often weighs about as much as a blog post. The blog post covers a topic with enough depth to feel meaningful standing on its own.
Of course that analogy makes perfect sense to a blogger, who regularly deals in units of "posts." But let's try the analogy from another angle. Let's consider a fast food scenario that portrays the reader as a consumer.
A consumer/reader stops in at McDonald's (which happens to organize its food like DITA elements) and asks for some food. How much food should the employee give the consumer?
The McDonald's employee puts several french fries on the serving tray and hands it to the customer. The customer eats the fries and must get in line to order some more food. The employee puts a couple of buns on the tray. The customer eats the buns and orders more food. The employee puts some cheese on the tray. The customer gobbles the cheese and orders some more. Finally the employee adds the burger on the tray. The customer eats the burger too.
As the customer leaves, he or she feels the experience has been unpleasant. The hamburger would have tasted so much better with all the elements assembled together in one sandwich, the customer notes.
And so it is with help. If you have a hamburger size of information, why split each element into its own topic and force the reader to individually retrieve/consume each piece, eating the cheese separate from the buns, and the buns separate from the burger, and the burger separate from the lettuce?
Information sometimes is much more understandable when presented together in one coherent "meal." By meal, I'm not talking about the whole grocery store (book) -- just enough to fill someone's appetite.
My Preference
Last week I wrote about collapsing sections and their usability. Despite the shortcomings of collapsing sections, they do present a much more attractive option for organizing content in a way that allows users to go directly to the task or concept they're looking for, without burdening users with information they don't want to see. You also end up with a smaller TOC so your help doesn't appear endlessly long.
I think smaller TOCs better align with navigation patterns on the web. Usually information architects think carefully about the information available on the first, second, and third levels of navigation. You often don't see information on the second navigation level until you navigate the first level. The third level doesn't appear until you finish navigating the second. There's an idea of progressive disclosure at work -- you give the reader enough information to guide him or her to down an appropriate path. You don't put all 600+ options on the first navigation level.
If you're following a 1:1 file to TOC entry ratio with DITA, though, you wouldn't have any need for collapsing sections. (If you did use collapsing sections, you'd end up with one collapsed section on the page, which would look confusing and incomplete, like a bulleted list that has just one bullet.)
Overall, I'd really like to use DITA, so I'm probably going to experiment with chunking. But I'm also concerned that such a large number of tech comm people might be following a method that leads them to put one paragraph per topic, and one topic per TOC entry. I don't know how such a method can result in a successful user experience.
I'm curious to learn how common chunking is among those who use DITA.
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.