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.
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.
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.
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.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, 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.