Search results

What does DITA-structured help look like?

Series: My DITA journey

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.

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.

About Tom Johnson

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.