Adobe Tech Comm Suite
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

Stitcher radio

Search results

Adobe Tech Comm Suite

Add a mini-TOC to your OxygenXML webhelp topics

by Tom Johnson on Nov 13, 2014
categories: dita

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:

minitoc

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.

Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

follow us in feedly