Adobe FrameMaker

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Adobe FrameMaker

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

Sep 22, 2014 • 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.


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

follow us in feedly

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include the following technical communication topics: Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, and certificate programs. I'm interested in information design, API documentation, visual communication, information architecture and findability, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.