Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

Adobe Robohelp

What does DITA-structured help look like?

May 15, 2014 • 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.

jivehelp

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.

cleartypes

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.

robustreuse

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.

hierarchicallinks2

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

shortdesc

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.

plainpdf

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.

parentlinks

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.

toclinks

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.

sourcecode

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:

linkstosections

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.


Get new posts delivered straight to your inbox.

Subscriber count: 3,220

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.