AODC Day 3: Help Authoring Tool Comparison
Posted by Sarah Maddox
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)
- 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
- 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.
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.
- 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 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.
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.
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.
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!
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.
About Sarah MaddoxTechnical writer, author and blogger in Sydney
Posted on 30 May 2010, in AODC, online help, technical writing and tagged AODC, contextual help, HATs, help authoring tools, Matthew Ellison, online help, technical documentation, technical writing. Bookmark the permalink. 14 Comments.
Leave a Reply Cancel reply
This site uses Akismet to reduce spam. Learn how your comment data is processed.
Thanks for this excellent summary. I totally agree with Matthew’s evaluation of the tools. (Although my opinion of the Madcap Flare help system is a bit different.) In case anybody is interested in a comprehensive list of many more Help Authoring tools, maybe the list on my web site can help. The URL is: http://www.indoition.com/online-help-authoring-tools-survey.htm
Wow, thanks for that link to your very comprehensive list of and comparison of HATs! Regarding the slight difference between Matthew’s evaluation of Flare and yours, I’m guessing that it’s mainly around the ease or difficulty of use.
Thanks for this analysis. It’s very helpful.
I used to be a Robohelp user. I think it’s a great tool for entry level writers because it’s so easy to use, and it has some beautiful output using Flash-based controls. But I gave it up in favor of FM and WebWorks which has been exceptionally usable for me and requires the least amount of work once it’s setup correctly. However, it does have a learning curve and takes some time to get used to.
Creating documents in Robohelp is like painting a picture. Creating documents in WebWorks and FM is like programming a robot to paint a picture. That’s how I’ve always compared the two.
It’s great to hear your endorsement of WebWorks ePublisher, along with FrameMaker. I haven’t used ePublisher in depth, but from an evaluation that I did a while ago, I could see that it has the potential to be very useful indeed. Thanks for letting us know.
I love your comparison:
“Creating documents in Robohelp is like painting a picture. Creating documents in WebWorks and FM is like programming a robot to paint a picture.”
“In particular, Matthew showed a useful workflow diagram for each tool.”
As a process & tools analyst/TechComm these workflows would have been useful to review, any chance they too can be shared or posted?
The diagrams are very useful indeed. Often Matthew Ellison makes his presentations available on his web site. I don’t know if he’ll be able to do that for this particular presentation. If he does, I’ll add a link to it here.
I am using CustomWare’s redirect plugin for context-sensitive help and having some issues. When users click on the help button in the application I support, they go to a redirect page and thence to the Confluence page. However, it is difficult to keep the CustomWare and Confluence versions synced. Right now, for example, the Customware redirect plugin is not working with Confluence 4.1.9.
Maybe using the redirect is the wrong approach.
What online help tools are people using with Confluence?
We use a combination of a properties file that we ship with the app, and a redirect that lives on our server. There’s some info in this post:
Follow the link in that post, which will lead you to another post that has follow-up information.
Thank you so much for this post!!! As someone relatively new to the technical writing community, I found it incredibly helpful. I’m not exaggerating when I say that I signed up for a WordPress account just so I could tell you how much I appreciated this beginner-friendly intro to HATs 🙂
Thanks for letting me know! I’m so glad it’s useful. Matthew Ellison did a great job in the presentation that these notes are based on. Things have moved on since 2010, but the overview is still useful.
I hope you enjoy WordPress. Next stop, a blog of your own. 😉
Hi there this is kinda of off topic but I was wanting to know if
blogs use WYSIWYG editors or if you have to manually code with HTML.
I’m starting a blog soon but have no coding knowledge so I wanted to get guidance
from someone with experience. Any help would be greatly appreciated!
Most blogware these days use WYSIWYG and other advanced editors, it depends on which one you choose. But coding is optional in most cases. Worst case scenario you may need to learn tagging to use intermediate and advanced features, but that is very small set of what some may actually consider coding or scripting.
There’s lots of information about blogware on the internet and side by side comparisons of features. If your Google-fu is strong write a simple query and just search for it.
This was a great read, thanks for sharing it. Without a doubt I would have to agree on the pros and cons you mentioned about Help Authoring Tools. I have used a lot of HATs such as ProProfs.com Knowledgebase, Author it, Madcap, content generator, Dr. editor and more. But I personally think that the most important aspect of an Authoring Tool lies in its applicational use. If a product is feature rich but you are not able to navigate through those features or not able to apply then it is just a waste of resources. “
Pingback: Help Authoring Tool Comparison from Sarah Maddox | I'd Rather Be Writing - Tom Johnson