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.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in , API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), 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.