Blog Archives

WritersUA 2011 Monday – Adobe RoboHelp’s commenting feature

This week Iā€™m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. One of the sessions that I attended today was an Adobe lab, run by Scott DeLoach, Kevin Siegel, Laurie Edelman and others.

During the conference, there were a number of “lab” sessions. The labs offer a number of computer workstations and software that we could use for hands-on experimentation. A few experts wandered around offering help and advice.

My aim in attending the Adobe lab

I decided to take a look at the latest version of RoboHelp. I have used RoboHelp extensively in the past, but not since RoboHelp 8.

In particular, I wanted to explore the new features in RoboHelp that allow you to gather feedback from users, and allow users to share comments among themselves. I had heard and seen this demonstrated in various places. The idea is that you have an online help system, shared amongst your users, even installed individually on their machines. Each user can add comments to their own version of the help, and share those comments with other users via a central server.

Exploring RoboHelp’s comments feature

In the lab there was no RoboHelp Server available, so we could not see the server side of the functionality in action. But I did manage to explore how it would work. Here’s what I did.

In RoboHelp, create your online help topics as usual. For the lab session, I used one of the sample projects supplied by Adobe.

The next step is to generate your help output, selecting Adobe Air as your output format. The Adobe AIR output is the only format that supports comments submitted by users. To generate the AIR output:

  • Choose one of the a “single source layouts” available. A single source layout basically corresponds to an output format. For this lab session, a few Adobe Air layouts were available. I chose “Adobe AIR – Role Based”.
  • Double-click the layout in the “single source layout” window. You get a popup where you can configure various options for the chosen layout.
  • On the “General” tab, choose an “Output Type” of “Adobe AIR Application“. This is the only output type that will allow comments from users. The other output types are hybrids that weave a Flash solution into an HTML web-based help system.
  • You will need a digital certificate. If you don’t have one (which is likely at this point!) you can generate a self-signed certificate for use while testing. Eventually you will need to get a certificate from a real certificate authority (CA). To generate a digital certificate, click “Create” next to “Digital Certificate”.
  • Supply a publisher name of some sort.
  • Specify a password for the certificate.
  • Next to “Save As”, specify a path and name something like “C:\cert.p12”.
  • Click “OK” to generate the certificate.
  • Click the “Collaboration” tab.
  • Select “Enable Topic Rating”, “Enable Commenting” and “Enable Comment Moderation”.
  • Set a password that the comment moderator will use.
  • At this stage, it would be good to specify the RoboHelp server to enable server-based storage and sharing of comments. I could not do this during the lab, because there was no RoboHelp server available.
  • Click “Save and Generate” to create your online help system.
  • Click “View Result” to see the resulting help files.

The AIR application will start up, showing your help topics in the help system. Now you want to add a comment to a topic.

  • Click the comment icon near the top left of the screen. (The icon looks like a couple of comment bubbles.)
  • A comment area will appear at the bottom of the topic.
  • To add a comment, click the plus sign.

Adding a comment:

Adobe RoboHelp's commenting feature

Adobe RoboHelp's commenting feature

Comments are displayed in reverse chronological order:

Adobe RoboHelp's commenting feature

Adobe RoboHelp's commenting feature

My conclusion

This looks pretty cool. As far as I could see, there’s no opportunity to add graphics or formatting to the comments. They’re plain text. Also, they’re not threaded ā€“ you can’t reply to a specific comment. Still, once a server is hooked up it is pretty cool for people to be able to share comments from their desktop apps. I’d be interested to see it in action, and to hear any experiences other technical writers may have had with this feature.

AODC – Adobe AIR Help

This week Iā€™m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. At today’s first session, Tony Self introduced us to AIR (Adobe Integrated Runtime) and two prototype AIR Help applications.

Tony is a founding partner of HyperWrite. His sessions are always amusing and information-packed. This one was no exception.

AIR

First, Tony introduced AIR itself. The acronym stands for “Adobe Integrated Runtime” and is produced by, you guessed it, Adobe.

In brief, here’s what happens:

  • As an author/developer, you will create an AIR application.
  • You will send the application to your users — it’s just a single file (extension .air).
  • Your users will install the AIR platform first, then install your application.

Since Adobe has such a wide following and presence, it’s thought that the AIR platform will soon be as prevalent as Flash, i.e. approximately 97% of computers will have AIR installed.

Here are some of the things AIR does for you:

  • You can create a rich desktop application, including graphics, HTML, AJAX, Flex and Flash.
  • An AIR application can be installed and run on any operating system. Well, in principle anyway.
  • Your application can include content from local and remote sources. Tony mentioned a good use case here: Your application could fetch the online documentation from the server if your user is online, otherwise it could default to the local copy of the documentation.

Two AIR Help applications

Next, Tony gave us an demonstration of two uses of AIR to produce online help systems:

  • Scott Prentice’s prototype AIR Help application
  • Adobe’s pre-release AIR support for RoboHelp 7

Scott Prentice’s prototype AIR Help application

Scott Prentice has created a prototype AIR Help application, using a DITA document as a test case (the DITA language reference). Scott’s application allows you to view the DITA document in a rich desktop viewer. The navigation panels include two different tables of content, an index and a search.

Adobe’s pre-release AIR support for RoboHelp 7

Adobe is building AIR support into RoboHelp 7. Currently, this is available as the pre-release RoboHelp Packager for Adobe AIR. The packager is free, and likely to remain so. It is also open source. It will probably become another output option in the RoboHelp UI.

To use the packager now — assuming you have RoboHelp installed:

  • Download and install the AIR platform.
  • Download and install the RoboHelp Packager for Adobe AIR.
  • Generate your WebHelp output from RoboHelp as usual.
  • Then run the packager, giving the location of your WebHelp files as input.
  • You will need a digital certificate. When you distribute your application, your users will use the certificate to verify the source of the executable file. For testing purposes, the packager leads you through the process of generating a certificate on your own machine. When you eventually distribute your AIR application, you’ll need a certificate from a recognised authority.
  • You can set various look-and-feel options, such as number of tabs, skins, branding. The number of available options will probably increase when the product is more mature.
  • You can configure your application to allow your users to add comments. Wow, Web 2.0 šŸ™‚ (More below.)
  • You can also configure it to update the local AIR Help file periodically from the server.
  • Click the “Generate” button — the packager will produce a file with the .air extension. This is the file you will distribute to your users.
  • Your help application supports context-sensitive help.
  • You can also bundle the help application with the product (application) it is documenting.

Now put on your other hat and become a user of your help system. Double-click the generated xxx.air file to install it.

  • You should see the content of your help file in the AIR Help viewer. It will look very similar to the RoboHelp WebHelp output. After all, it’s the same HTML.
  • It includes a search facility, which also shows a summary of the contents of the pages in the search results.
  • There’s also an index.
  • It allows users to add “Favourites” — this is difficult to do in straight HTML-based help.
  • The “How do I” facility is similar to RoboHelp’s Browse Sequences.
  • There’s a sophisticated zoom utility to increase text size.

A bit more about the comments in the Adobe AIR Help

When you use the Adobe packager to create an AIR Help file, you can configure your application to allow your users to add comments.

A user can then add comments to the help topics. By default, the comments are stored on the user’s local machine. Each user can see a list of and review their own comments. They can also choose to synchronise their comments with the server. Then their comments are visible to other users, and they can see other users’ comments.

Tony mentioned that this is a bit of a trend in online help software, for example MadCap Flare can now run with the MadCap Feedback Server, which collects comments as well as information about how the users are using the system. This is useful, for example, to diagnose troublespots in the help system and the application it is documenting.

My conclusions

Tony‘s session was very interesting to me, because I’ve produced various help systems such as WinHelp, HTML Help and straight HTML files, using RoboHelp, Help & Manual, HDK and others lost in the mists of time šŸ™‚ From the little bit I’ve seen today, AIR Help is one to keep an eye on. It’s not a leap into the future, but it has some useful advantages over CHM files and vanilla HTML.

%d bloggers like this: