Publishing to Adobe AIRHelp

This blog has been written by this month’s guest blogger, Jason Nichols of ReadSoft. Thanks Jason!

A few years ago our Technical Communication team upgraded to Adobe’s Technical Communication Suite 2. One of the reasons why we decided to get TCS2 was the ability of RoboHelp 8 to output to Adobe AIR—at the time a brand new publishing platform. (And not just for technical documentation, but any application. TweetDeck is perhaps the most famous example.)

There are a few reasons why we publish to Adobe AIR, which I’d like to explain below.

Modern look and feel

Technical documents have moved a long way from the days of WinHelp and Compiled Help (CHM files). The first thing that strikes you when looking at AIRHelp is that it’s modern:

https://blogsimages.adobe.com/techcomm/files/2011/12/jasonblog.png

UI of AIRHelp

Documents that sell

Technical documents also market your organisation, in the same way a website does. An old website built on old technology with outdated colour schemes is going to have a negative effect on visitors. If I was a potential customer browsing the documentation, and it looked outdated, I would definitely think the company was old-school. I would lean more favourably toward the organisation that looked modern.

So this is a general tip for all you tech writers out there: Irrespective of what output(s) you produce, spend some time making it look cutting edge (at best) or up-to-date (at least).

Online/offline modes

AIRHelp can act as a web browser and display content not contained in the original AIR file, but rather content on a web server. Our content is updated continuously, between product releases. (This is because there is always so much to document!) A major product release may be the current one for a whole year, but fixes and service packs are always released in between. In this typical software release schedule, it obviously makes sense to be able to update and improve the documentation at the same time. Or, better, anytime!

We host our Help content on a web server as well, as HTML pages (also generated from RoboHelp). This week I updated several topics in a guide and added a few extra ones. I then generated the Help and published the new HTML output to the web server. And anyone with the AIRHelp installed and an Internet connection will see the new content without having to do anything.

The benefits for consultants

Being online though can sometimes be a luxury. Our consultants—those that perform installations and configuration—often don’t have Internet access when they are on a customer’s site. But they still need the documentation. So they take the AIRHelp with them on their laptops. When they come back to the office, the content can be updated.

This is a much better solution than PDFs. PDFs cannot be updated. They are static, passive. One of the big problems we had is that a lot of our consultants were walking around with documentation that was literally years old. They have heavy workloads and I can imagine they don’t have the time to check for new versions. But as a result we always had technical and support questions about various issues that they could not find the answer to in the documentation because it was an old version.

Whither printed documentation?

We’re really trying to push PDFs into the background and to get people to use AIRHelp and our HTML pages instead. It takes a lot of time to publish a document for print purposes. I mean, we use RoboHelp to generate Word documents and macros to apply final formatting and create the PDF. But a significant amount of time is taken with fixing small formatting issues. This is the nature of printed documentation—each page has to look right. And in our case (and not just for us) people rarely print out an entire guide. They just want to browse the contents and look for a particular piece of information.

Commenting function

AIRHelp gives readers the ability to add their own comments to a topic. We’ve used this for peer reviews. However, we use RoboHelp 8 and the ability to administer comments (view, edit, delete) is limited. I’ve heard this has been improved in RoboHelp 9 but I haven’t yet looked at it.

Conclusion

In summary, we use AIRHelp because of its modern look and feel, it’s ease to push out updates, and because it has an offline mode which is a must-have for our consultants.