Using collapsible sections to bring tasks and concepts together (DITA)

by Tom Johnson on Sep 22, 2014
categories: dita

Last week I showed how to integrate a sliding side panel into OxygenXML's webhelp output. In this post, I show you how to integrate collapsible show/hide sections. As before, I'm using DITA as the structured content, which adds another element of complexity to the setup.

Demo

For a demo of the show/hide functionality, see Show/Hide Demo.

In this demo, the content shown in the first collapsed section is actually transcluded from another page. The other sections contain content directly on the page. (If you use a General Task element, you can include sections before the steps.)

For step-by-step instructions on implementing this Simple-expand jQuery plugin into OxygenXML, see Add a jQuery show/hide toggle.

Combining tasks and concepts

Through collapsible sections, you can combine content that is often organized separately in help material. For example, in my help, I have a page on activating a license (a task). I have another section that explains details about the license (a concept). Traditionally these sections are separated in DITA-authored help because the strict task and concept topic types don't mix. With a strict task, you can't add sections before your list of steps. You can only add sections before steps with General Task elements.

In previous posts, I already debunked myths about tasks and concepts needing to be separate (see DITA's output does not require separation of tasks from concepts). There is no compelling reason to always separate tasks from concepts. Instead, it's better to consider user goals and decide whether it makes sense to combine the information into a single topic.

If you follow the philosophy of every page being a self-contained unit of information that allows a user to reach a goal, then in many cases it really will make sense to combine tasks and concepts.

For example, with my topic on activating a license, it might be important for the user to know what features the license controls, the format of the license, the configuration parameters of the license, and other license details. All of these details might be essential if the user is having trouble activating the license.

Through collapsible sections, you can bring the conceptual information into the topic before the list of steps but collapsed so it's not in the way of the task. Alternatively, you could collapse your tasks and leave the conceptual information expanded. You have a lot of flexibility.

Previous experiences with collapsible sections

I've written several times about collapsible sections (see the related links at the bottom of this post). In re-reading these other posts, I see that I am sometimes persuaded that collapsible sections are the ideal solution, so I go to the trouble of implementing them across my help, and then later decide they are problematic. As a recap, then, here are pros and cons for collapsible sections.

Pros for collapsible sections

• Reduces the number of topics in your TOC, increasing findability of information.
• Centralizes needed information into the same page so users can better achieve their goals.
• Brings information together that belongs together, helping avoid information fragmentation and navigation ping-pong.
• Allows users to easily scan a page for all information and go directly to the section they need, rather than scrolling.
• Follows a model of progressive information disclosure, allowing users to customize the amount of information they want to see.

Cons for collapsible sections

• Not needed for short pages, only for long pages. If most of your pages are short, there's no need for collapsible sections.
• Can result in inconsistent displays, with some pages containing collapsed sections and others not. Inconsistent formats reduce the predictability of user experience.
• Requires you to add the ability to expand all sections at once on a page, but this becomes problematic not all pages need this button.
• Doesn't auto-expand search results that appear within a collapsed section.

While I have used collapsible sections with Flare and Drupal, I haven't yet used collapsible sections with DITA. However, I think collapsible sections would make a particularly good application to DITA since DITA-authored help by nature tends to result in a lot of tiny little topics.

Regardless of the usability of collapsible sections, I'm excited about how easy it is to integrate jQuery functionality into OxygenXML's webhelp output.

Related posts

• Collapsible header sections — more problematic than helpful
• Using the Proximity Principle to Design Online Help Navigation
• How to Organize Page-Level Content