Add a mini-TOC to your OxygenXML webhelp topics
A while ago, I posted a tip on adding collapsible sections to the OxygenXML webhelp output. Collapsible sections have their place, but more commonly now, users seem to prefer long pages that they can scroll. For this behavior, it's better to add a mini-TOC near the beginning of the page that lists the sections on that page. As an example, look at pretty much any page on Wikipedia.
Here's what my mini-TOC looks like:
I used a jQuery plugin called Table of Contents to incorporate the mini-TOC functionality within OxygenXML's webhelp output. Instructions for implementing the mini-TOC are here: Add a mini-TOC on a page. To see the demo, visit my Mini-TOC demo page.
I have also started to use the general topic instead of the specialized task, concept, and reference topic types. With the general topic type, it's easy to add the sections you need for a page that might mix instructions with conceptual information. As your page gets longer (usually 3 sections or more), it's a best practice to put a TOC near the top.
I know it's nothing revolutionary, and for DITA authors whose average page count is 50 words this might not ever apply, but I'm happy with this much-needed mini-TOC feature.
About Tom Johnson
I'm a technical writer based in the San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.