What does DITA-structured help look like?

by Tom Johnson on May 15, 2014
categories: dita

While documenting something yesterday, I ran across a help file that was unmistakably written in the DITA XML structure. Check out Jive's help here. Jive is a community platform, kind of like SharePoint but more modern and clean looking. The webhelp output is published with Eclipse.

How can you tell when help is written using DITA? There are several giveaways.

Clear topic types. There's a pretty clear distinction between concept and task topic types. This is a task topic, as you can see with the short paragraph followed by a numbered list of steps.

Not all the topics follow strict types. For example, the topic Connect to Your Community is a concept topic that uses steps. I noticed this in quite a few places.

Robust re-use. If you look in the upper-right corner, there's a "Switch to User Docs" link. The user version has many of the same topics, but re-used. There are also about 5 or 6 other help files based on different versions of Jive. DITA allows for robust re-use.

Hierarchical links on folder parent pages. The overview topic for each folder contains a list of hierarchical links. The hierarchical links are links to each of the child pages in the folder.

Short descriptions. Most topics have a summary sentence right below the title. This is the shortdesc element.

PDF versions of chapters. Many of the chapters have PDF versions. The PDFs are actually the default PDF processing from the Open Toolkit, in all its plainness.

Links back to parent topics. Many of the articles have links back to parent topics at the bottom. These links are automatically added by DITA when you create topic hierarchies.

Master TOC. The table of contents is pretty extensive. I'm imagine that it's comprehensive except that it doesn't include their API/developer documentation.

Open Toolkit styles in the source code. If you view the source code of the pages, you can see all the familiar classes the Open Toolkit uses when it processes DITA. These classes include things like title, section, shortdesc, taskbody, li step, li choice, etc.

A couple of unexpected things

I did notice a couple of unexpected things. There aren't any relationship table links. Instead, the writer uses (albeit sparingly) inline links. Additionally, some topics that contain multiple sections link to the sections in steps. Here's an example:

The linked pages don't appear in the TOC. I'm not sure why the authors chose this method instead of using the chunk "by document" attribute. The links are xref inline links.

Overall, I found the help pretty easy to navigate and browse around. The search is decent. It's unfortunate that the Eclipse frame URLs are static. But navigating from topic to topic is fast and clean.

Also, I wanted to note that DITA help outputs can probably look quite a bit different. It's not like spotting a Robohelp webhelp file, because DITA can be transformed into so many different systems and platforms. DITA Writer has a good list of sample DITA help material here.

Next: 1.8 Content Re-use is so much better with DITA (and esp. with OxygenXML)