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 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.