Blog Archives

AODC Day 3: Help Authoring Tool Comparison

Two weeks ago I attended AODC 2010, the Australasian Online Documentation and Content conference. We were in Darwin, in Australia’s “Top End”. Over the last couple of weeks, I’ve been posting my summaries of the conference sessions, derived from my notes taken during the presentations. All the credit goes to the presenter. Any mistakes or omissions are my own.

Matthew Ellison presented a number of excellent sessions at this conference. His Friday session was called “Help Authoring Tool Comparison”. He discussed what a help authoring tool (HAT) can do for us as technical writers, then did a detailed comparison of a few popular tools.

What a HAT can do for you

HATs hide the complexity and allow you to concentrate on the content. You don’t need to worry about coding and scripting, conditional tags and other mechanics under the hood.

HATs produce some very nice output, such as browser-based help (WebHelp), PDF and many other types. On the whole, HATs produce the tri-pane output format of online help. If that’s what you need, they make it very easy to do.

They provide help-specific features such as context sensitivity, indexing, dropdowns and related topics.

You can also use HATs for single sourcing.

In summary, HATs cater to our specific needs as technical writers.

Things that may count against a HAT

HATs tend to be proprietary and non-standard. For example, a HAT that supports DITA may not use compliant DITA. This may mean you’d find it difficult to migrate to a different tool. It’s a trade-off between the ease of use and the loss of flexibility.

Compared to a full CMS with XML management, HATs offer limited facilities for content re-use and content management.

Examples of HATs

Matthew emphasised that all the HATs he discussed are excellent tools. His presentation covered the following tools, which are the most popular of the HATs available:

  • Adobe RoboHelp (also TCS2, which contains a slightly different version of RoboHelp that offers better integration with FrameMaker)
  • Author-it
  • ComponentOne Doc-To-Help
  • EC Software Help & Manual – a really nice tool.
  • MadCap Flare
  • WebWorks ePublisher – This tool has been around a long time. It’s not an authoring tool, but rather converts content from one format to another.

Matthew gave us a list of the features that almost all HATs have in common. Then he discussed some criteria for selecting a HAT, examining a number of tools and analysing the strengths and weaknesses of each tool. He covered the following aspects of each tool:

  • A short description of the tool
  • Workflow
  • UI and usability
  • Key strengths
  • Key weaknesses
  • The tool’s own help

I didn’t have time to take notes on everything covered in the presentation. Here follow the notes that I did take.

Adobe RoboHelp

RoboHelp stores its content as XHTML. You work on topics, basically one topic per file. RoboHelp publishes to a number of different formats. The output to AIR Help and WebHelp are very good indeed.

I found this point interesting: If you want a printed document, Adobe recommends that you write your documents in Microsoft Word and link them to RoboHelp as the publishing engine. When printing, print the Word document. For other output formats, publish via Robohelp. You can print directly from RoboHelp, but the output is not great.

If you have TCS2 RoboHelp, you can link FrameMaker documents in the same way as Word documents. FrameMaker gives you a much richer print capability.

The RoboHelp UI and usability are good. RoboHelp goes to some pains to retain a Word-like UI (pre-2007 Word). The UI for linking and importing is not so good.

Other notes:

  • You cannot share resources (stylesheets, icons, snippets) across multiple projects.
  • The download file is very large.
  • RoboHelp’s own help is not all that great, chiefly because it contain features that you cannot create from RoboHelp itself. The information is also not very well structured.

Author-it

Author-it stores its content in a single library in the database. You can connect to your own database: SQL Server or JET / SQL Server Express (free). On the minus side, Author-it stores the content in a proprietary rather than a standard storage format.

Author-it offers a very powerful capability for content re-use.

You can publish to a number of different output formats. All print outputs are generated via Microsoft Word. This can be seen as clumsy and a problematic dependency. It does produce excellent Word documents.

The UI is very complex, requiring a steep learning curve. It has a very modern look and feel.

Author-it has a number of capabilities, probably the longest list of all the HATs. Some of the add-ons are very powerful, such as authoring memory which tracks duplicate content. It has good support for localisation. Another feature offers web-based authoring too.

The help system is pretty good, and is recognisably generated from Author-it itself. It’s also mirrored on the web, so you can find the information via Google too.

ComponentOne Doc-To-Help

This is the original HAT. Originally the idea was to work in Word and convert to Doc-To-Help. But now you can also choose to edit in XHTML using the Doc-To-Help WYSIWYG editor.

To create styles, you actually create Word .dot files. At first use, this seems a bit odd. Doc-To-Help generates CSS from the .dot files.

It also has a database where you can store metadata.

Doc-To-Help offers a number of output formats.

The UI has improved over the years. It’s a professional-looking, ribbon-based UI.

Doc-To-Help has some cool features, such as the ability to create relationships between topics, similar to the way Author-it does.

It also integrates with Microsoft Sandcastle for documenting class libraries based on comments in the code.

Doc-To-Help’s own help is good.

EC Software Help & Manual

Help & Manual has a very nice WYSIWYG editor, where you edit in XML. It has its own DTD.

It imports content nicely. If importing from Word, save to RTF first. There’s no FrameMaker or DITA support.

The UI is very nice. Of all the tools, it’s the easiest and most comfortable to use (even though ribbon-based). The UI is driven by the table of contents. It offers a simple user experience, yet there are some good advanced features which you can find if you look for them.

One great advanced feature is the skins that you can use to achieve consistency across projects. You can also share resources, such as style sheets, across projects.

MadCap Flare

All editing in Flare is in XHTML, using the WYSIWYG editor.

Flare does a very good job of producing print and help output formats. There’s also a WebHelp Mobile output

You can input DITA, as well as other formats.

The UI is fairly easy to learn, but has some stumbling blocks. You do need to understand CSS to get the most out of it.

Flare has the most excellent help system Matthew has ever seen.

Offering your users the ability to collaborate on your help pages: As an add-on, you can buy the collaboration module so that users can comment on the topics and read each others’ comments.

WebWorks ePublisher

Note that ePublisher is not an authoring tool. There is no editor. You use it to publish content from Word, FrameMaker or DITA to a large number of output formats.

ePublisher offers a large number of mappings that you use map from your input styles to your output styles.

The UI and usability is slightly confusing. There are actually two products involved. ePublisher Express is very simple. That’s the one you use to publish the output. ePublisher Pro is where you create the mappings, and the UI is more complex.

The WebHelp output is not very pretty or professional. The TOC (table of contents) output is fixed by the TOC of the source document.

ePublisher’s own web-based help, published on a wiki, is just bad. On the other hand, the local help that you get when you install the product is much better.

Final comments from Matthew

Always test drive with real data before buying a tool. All the products discussed in this presentation are great tools!

My conclusion

This was a very thorough and in-depth analysis of the features, strengths and weaknesses of the most popular HATs around. I didn’t have time to take enough notes to do it justice. In particular, Matthew showed a useful workflow diagram for each tool. Thank you Matthew for another great presentation.

Confluence wiki to Eclipse Help the easy way – Scroll FTW

How cool would it be to write your documentation and online help content in Confluence wiki and convert it to Eclipse Help format at will? The K15t Software guys have just announced the latest version of Scroll Wiki Exporter, Scroll 1.2, including a new exporter for Eclipse Help and JavaHelp.

So I tried it. It works. 🙂

Why am I focusing on the Eclipse Help conversion?

It just so happens that Atlassian, where I work, has a product called the Atlassian Eclipse Connector. It’s an Eclipse plugin. At the moment, we write and publish the documentation for that product on our Confluence wiki, along with all our other documentation.

I’m wondering whether we could export the docs to Eclipse Help format and ship them with the connector, so that developers can use the documentation inside the Eclipse IDE. After all, that’s where people are using the connector itself.

Getting Confluence and Scroll

Download Confluence and install it, following the installation and setup guide. You can get a free 30-day trial licence or a free personal licence. I’m using Confluence 3.2.1. Actually, it’s the rather verbosely named 3.2.1_01. 😉 and it’s the most recent version of Confluence at time of writing.

Scroll Wiki Exporter is a plugin for Confluence wiki, supplied by an independent company called K15t Software. You can get a free 30-day trial licence for Scroll too. Follow the installation guide to download and install the Scroll plugin into Confluence.

Hint: For some reason, I could not find the Scroll plugin using the Confluence “Plugin Repository” option. I used the alternative option — download the JAR file from the Scroll web site, then upload it into Confluence via the “Plugins” option in the Confluence Administration Console.

Writing your topics

The Scroll team provide some useful tips for getting the best out of Scroll. For example, you can see how Scroll handles heading levels and check the supported Confluence macros and wiki markup. See the Scroll authoring guide.

Using Scroll to export Confluence pages to PDF and DocBook

A while ago I wrote a post with some pretty screenshots about using Scroll to export wiki content to PDF and DocBook. You can still do this with the new version of Scroll, of course!

Exporting to Eclipse Help format

Once you have installed the Scroll plugin into Confluence, you will see a new item in the Confluence “Tools” dropdown menu, called “Scroll Wiki Exporter”:

Confluence wiki to Eclipse Help the easy way

Confluence wiki to Eclipse Help the easy way

Click that option to see the Scroll export screen. At the top, it shows the title of the wiki page you were on when you clicked the “Scroll Wiki Exporter” menu option. In my case, the page is named “Atlassian Connector for Eclipse”. This will also be the top page in the tree that the exporter will process. Your output file will contain this page and all its children:

Confluence wiki to Eclipse Help the easy way

Confluence wiki to Eclipse Help the easy way

Go to the “Formatting” tab and select “EclipseHelp (*.jar)” as your format:

Confluence wiki to Eclipse Help the easy way

Confluence wiki to Eclipse Help the easy way

Click the “Export” button at the bottom of the screen, and wait a while. When the export has finished, a new screen will appear offering you the output file for download:

Confluence wiki to Eclipse Help the easy way

Confluence wiki to Eclipse Help the easy way

Hint: If you are using Windows,  you may find that the file is automatically renamed from a “.jar” to a “.zip” file. Change the extension back to “.jar”.

The output

What you get is a JAR containing the files required by the Eclipse platform, to be able to incorporate your help files into the Eclipse IDE. The JAR file has a name corresponding to the title of the page you selected, plus the version of the page. For example, my JAR file was called:

Atlassian_Connector_for_Eclipse-37.jar

Looking inside the JAR (it’s just like a zip file) you see:

  • A top-level folder. Mine was called “com.example.plugin_37”.
  • A “download” folder, containing an “attachments” folder and a lot of numbered folders. This is where you’ll find your Confluence screenshots, images and other files that were attached to your wiki pages.
  • An “images” folder with the stock Confluence icons.
  • A “plugin.xml” file, defining the help plugin to Eclipse.
  • A “toc.xml” file, defining the table of contents to Eclipse.
  • A number of HTML files containing the content from your wiki pages.
  • An HTML file called “index.html”, which is the top level of your HTML tree. Click this one if you want to view your help files in your browser. 🙂

Here’s what the extracted JAR looks like in Windows Explorer:

Confluence wiki to Eclipse Help the easy way

Confluence wiki to Eclipse Help the easy way

Here’s what one of the pages looks like when viewed in Firefox browser. Note that the annotated screenshot on the page comes from a Gliffy diagram in Confluence. It’s exported as a PNG file in the Eclipse Help format. FTW! Gliffy is a plugin you can use to draw awesome diagrams on your wiki pages, so it’s great that Scroll is able to export Gliffy diagrams too.

Confluence wiki to Eclipse Help the easy way

Confluence wiki to Eclipse Help the easy way

Putting the help file into Eclipse

When doing things properly, you will need to associate your help file with the Eclipse plugin that it’s documenting, and hook up the context-sensitive help links too. The Eclipse documentation guidelines have all the details.

For a quick thrill, you can simply extract the files from the JAR file and copy them into your Eclipse “plugins” folder. I’m using Eclipse 3.5 (Galileo) on Windows Vista. My “plugins” folder is at this location:

C:\Program Files\Eclipse 3.5 Galileo\plugins

I copied my “com.example.plugin_37” folder and all its children into the “plugins” folder. With huge anticipation, I started Eclipse and clicked “Help”. Ta da! ♪♫♬

Confluence wiki to Eclipse Help the easy way

Confluence wiki to Eclipse Help the easy way

(Click the above image to see a larger version.)

The “Contents” panel on the left shows the default 5 help topics that come with Eclipse, followed by mine. My set of help topics is the one called “Atlassian Connector for Eclipse“. For the sceptics 😉 here’s an even bigger screenshot showing the full Eclipse SDK with the help window open:

Confluence wiki to Eclipse Help the easy way

Confluence wiki to Eclipse Help the easy way

Other points of interest

One thing I was concerned about was the performance hit on a Confluence instance, if random people start exporting the content to various formats, and in particular to PDF as its conversion is known to be a bit of a resource hog. The Scroll guys have thought of this, of course. Their documentation explains that Scroll uses the Confluence “export space” permission, so you can limit the number of people who can do the export and make sure they know the possible performance considerations.

Scroll happily converted my {toc} macros into links, and made useful decisions about dividing content into help topics.

Things to investigate further

I did all this investigation and experimentation in the course of an Atlassian FedEx Day. That’s when we get 24 hours to do something cool. (I blogged about another FedEx Day a while ago.) There’s only so much time in a FedEx Day, so there are still some things to follow up on.

I encountered a slight problem with my Gliffy diagram. The export itself worked, converting the diagram to a .png file. When you view the HTML files via a web browser you can see the Gliffy diagram. (There’s a screenshot above.) But when you view the same page in Eclipse, the image is missing. The .png file is in a “temp” folder within the JAR, so maybe Eclipse Help can’t find it there. I’m sure the Scroll team will know the answer. Here’s the location within my JAR file:

download/temp/mypic.png

Scroll offers a macro and a label that you can use to exclude pages and text from the export. I haven’t tried them, but they look very useful.

To make the help files really useful within Eclipse, we’ll need to hook up the context-sensitive help from our Eclipse Connector plugin to the relevant topics in our help plugin. Then we could ship the help plugin along with the Eclipse Connector plugin itself. I haven’t looked at this yet.

Conclusion

Scroll’s conversion to Eclipse Help looks very useful. I’ll recommend to our Eclipse Connector development team that we follow up on it. 🙂

AODC day 2 – Design of context-sensitive help

This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today is the second day of the conference.

Here are some notes I took from the session on user-centred design of context-sensitive help, by Matthew Ellison. I hope these notes are useful to people who couldn’t be at the conference this year. The AODC organisers will also publish the session slides and supplementary material once the conference is over.

User-Centred Design of Context-Sensitive Help

With a laugh, Matthew introduced himself:

“I am the equivalent of Tony Self but with a funny accent and a better shirt.”

In this presentation, Matthew concentrated on the information design side of things, rather than the technical implementation of context-sensitive help (CSH). He gave us a definition of CSH: “Direct access to help that is focused on the user’s current needs.” In practice, he said, we tend to provide help based on where the user is in the UI.

What do we mean by “context”? The more we can tie it down, the better help we can provide. For example, we might be able to detect and respond to: The window/dialogue/tab the user is on; the control they’re trying to use; the zoom level or other settings; previous history, such as other screens visited; role; printer connectivity and so on.

Looking to provide user-centred help, let’s look at how users behave with respect to help:

  • Most people don’t consult the help ahead of time.
  • They’re usually busy with the task when they need help.
  • They’ll only use help if they think it will give them useful information. So Matthew says they’re unlikely to click a little question mark, because it is not a convincing indicator of useful information.
  • They want to be interrupted for as short a time as possible.

We also need to consider the questions a user may ask when confronted with a task or screen. For example: What is this screen for? What do I need to enter in this field? Matthew thinks it’s unlikely they want task information in a context-sensitive topic, because they’re already busy with the task.

Matthew has noticed that some software vendors are moving towards procedural rather than reference topics. (For example, see the CSH for MadCap Flare from versions 3 to 4.) Apparently this is in response to feedback from users. But Matthew thinks this may be a misdirection.

As a consequence, one mistake the Flare help makes is to pack all the reference information into the step in the task topic. So for example, there may be a single step that tells you to complete the options on a screen. This step will now be very long because it contains all the reference information about each option.

By the way, Matthew remarked that he is a great fan of MadCap help.

In the Captivate help, the help links are now labelled as “Learn more” with an information icon. Unfortunately the help topics are very long, especially for online help use.

So Matthew thinks the CSH topics should answer the questions: “What is this? What should I enter? Which should I select?” And the topics should be written specifically for CSH rather than linking only to documentation written for other purposes.

Now Matthew discussed IBM’s Task Support Clusters, designed by Michael Hughes. The idea is that most people who use their help are coming in via CSH. They press help within the application rather than coming in via search.

So IBM identified the locations in the application where help is needed, and then built a self-contained group of topics that support that particular task.

Start with a keystone concept topic (provides critical conceptual information), then provide related tasks and reference. The topics in a cluster are all interrelated by links pointing to each other, but there are no links that point outside the cluster. So the users cannot get lost by following links all over the help system.

The idea is that 80% of the time, the users will read the keystone concept topic and that will be enough. Don’t try to answer all questions in this topic, just the most likely questions users will have.

Now Matthew discussed contextual help. This is additional information that’s actually part of the application and supplements the UI. It’s more likely that people will read this, because they don’t have to open up the help.

This is inline help, available via popups or expanding/dropdown text, or just simply on the screen. This help must be well written, because there’s very little space. Recommended length is one to three short sentences for the entire page. But just one phrase or sentence for a single field.

For the help links, use the actual question the user may ask e.g. the link might say “What is a member name?” When you click it, you get a popup answering the question. Or “See some examples” might pop up some example values for a particular field.

MadCap Flare has this kind of popup help. They’re also working on the functionality that will allow us to put it into our own help systems when using Flare — currently only for DotNet applications.

Quick help or popups should link to full help system for deeper information. MadCap Flare is doing this in their new popup help.

SnagIt’s balloon help is great — it knows what you’ve just done and suggests what you might want to do next. After a while the balloons disappear, because it assumes you know how to do it now.

Also guided help may be a good way of providing procedural help. See Matthew’s presentation from last year’s AODC conference. The application guides you through your task and actually stops you from doing the wrong thing. SHO Guide is a very interesting product that allows you to do this.

Thank you for another great session, Matthew.

Using a wiki for online help

Online help — it’s a technical writer’s dream. We all want to design and write online help systems, and we all know that context-sensitive help is the way to go. Can you do it on a wiki?

Yes 🙂 I wrote an article on the Atlassian News site this week, illustrating how we’ve used our Confluence wiki to provide context-sensitive help in the latest FishEye and Crucible software releases. Have a read. It’s got some pretty pictures as well as the technical stuff 😉

Clarifying my terminology: By ‘context-sensitive help’, I mean that when you click a help link on an application screen, you get the instructions directly related to that particular screen. Also at a deeper level, when you click a help icon next to a field you get help on that specific field. We’ve provided both these levels of help, as described in the above article. Another type of contextual help is when you hover your mouse over a field and a short description pops up in a kind of bubble. That’s usually called a ‘tool tip’, and is not what I mean here.

I’ve written a number of online help systems for various companies, using a variety of tools. My favourites were Help and Manual and RoboHelp. I’ve also dabbled with HDK (the precursor to XDK) and with Microsoft’s ‘raw’ HTML Help editor. And now I’m using Confluence wiki.

What’s the difference between a wiki and a help authoring tool? Well, there’s a big difference, of course. A wiki is essentially a collaboration platform — your online documents become a place where everyone goes to find information, share their own tips with others, and pick up the latest updates. A help authoring tool is tailored towards building a documentation set which is essentially static (even if you update it every day, it’s still not a discussion platform) but which has all the bells and whistles of an integrated online help system.

Most help authoring tools provide the following functions. You’ll probably have trouble finding a wiki which supplies these functions to the same degree:

  • Fully customisable table of contents, where you can put topics in the order you want, omit topics, or make a single topic appear more than once.
  • Integrated keyword index.
  • Integrated glossary.
  • Navigational tools to make topic browsing easier, such as the ‘browse sequences’ provided by RoboHelp.
  • Topic linkage tools, such as the ‘next topic’, ‘previous topic’ and ‘related topics’ tools which are built into some help authoring tools.
  • Generation of HTML Help (.chm) and WinHelp output files.
  • Workflow support (draft, review, publish).
  • Integration with a source control tool such as VSS, or RoboHelp’s inbuilt check-in check-out manager.
  • Automatic generation of topic IDs, which you can hand over to a developer for plugging into the code to generate context-sensitive help links.
  • Sophisticated topic templates.

That’s a long list. So what does a wiki provide, in terms of usefulness for online help?

  • A wiki page is just a URL — so you can link to the page directly from your application screen. (Read my Atlassian News blog to see how we’re doing it with Confluence.)
  • Wiki pages are continuously being updated and enhanced by technical writers, support staff and even customers who have useful tips to share. So when someone clicks the help link, they get the most up-to-the minute information possible.
  • Wikis allow you to embed multimedia goodies such as images and Flash movies.
  • You should be able to generate PDF, HTML and XML versions of your wiki pages.
  • A good wiki has a good search engine.
  • Some wikis provide version control — all changes are tracked, and you can see who made each change or even revert to a previous version of a page.
  • A wiki often provides tools for runtime integration with other software — many wikis allow you to install plugins or addons which display information directly from another platform. For example, a wiki page can show a list of bug fixes drawn dynamically from an issue tracking system like JIRA.
  • Some wikis allow blogging as part of the wiki platform. So your documentation page can embed a list of the latest blog posts related to the topic of the page. The blog posts will always be the most recent as at the time the user views the wiki page.
  • Your wiki is sure to have a number of other interesting features which you can use to work around some of the shortfalls listed above. If you’re interested, take a look at my previous posts on using wikis for technical documentation.

In short, wikis are different. They’re not necessarily better or worse — it depends what you need for your documentation system. Wikis are fairly new, so they’re developing all the time. I’m having fun riding the wave 🙂

%d bloggers like this: