Xtensive – News Blog: Online web help: industry standards, help browsers \ converters and help authoring tools

Abstract: this article might be helpful for you, if you ever considered publishing product help on the web. It provides a short review of online help browsers used by market leaders, as well as widely adopted commercial and freeware solutions allowing to publish product help on the web. So if you're planning to publish help files for your product on the web, you'll be aware of all the options, as well as of standard user expectations.

Disclaimer: since my company has its own product in this category, I can't pretend to provide fully independent review of various help browsers. But I'll try to.

What is really important for your potential (or existing) customers browsing your help? There are many factors (documentation quality itself, usability, design), but finally all of them can be expressed as overall user experience in comparison to widely known help browsers on the market, such as online MSDN Library web site or Visual Studio .NET Help.

Online help browsers used by market leaders

Microsoft MSDN Library
URL: http://msdn.microsoft.com/en-us/library/default.aspx

Nice features:

3 versions – Classic, Lightweight Beta, ScriptFree
Search with hints, but only in Classic version!
Good URLs
Good print version
Community content (comments), "Rate the article".

Notes:

No index - likely, because it must be incredibly large there
I don't understand why it always reload the whole page. In general, this makes impression of slower operation.
Open TOC nodes get closed on navigation (except the ones in current navigation path).

Summary: really good browser for such a large help collection.

Adobe Online Help
URL: http://help.adobe.com/en_US/Acrobat/9.0/Professional/index.html - for Adobe Acrobat

Nice features:

Comments, rating - with RSS
Good design
Good URLs (but see the notes below - it looks like plain HTML everywhere)
No need for Print button :)

Issues:

TOC disappears when you click on a TOC link
TOC always gets completely loaded.

Notes:

No AJAX, no frames
No index
Search there relies on global search at Adobe.com.

Summary: this is mainly plain HTML (except comments), with all the limitations. The same approach won't work for large help collections (references, etc.). But Adobe team made really a good job - all the exposed documentation there is relatively short.

Autodesk Online Help

URL: http://download.autodesk.com/us/maya/2010help/ - for Maya

Issues:

Top frame URL does not change. It seems there is no way to get link to current page.
Keyword and search indexes are fully loaded into the browser on navigation to corresponding tabs. Chrome process immediately eats ~ 200Mb.
It seems search is implemented in JavaScript.
No "Print" button.
Buggy splitter (IE8, Chrome, Firefox 3.6).
I'd say, design looks a bit ancient ;)

Summary: an attempt to provide Windows Help user experience there looks at least as unfinished.

JetBrains WebHelp
URL: http://www.jetbrains.com/resharper/webhelp/ - for ReSharper

Nice features:

AJAX TOC with sync on navigation
Search on the right is good solution for wide screen (now it is the most frequent case, especially for developers).

Issues:

No URLs. Permalinks are available, but they lead to pages without header, TOC and Search.
No highlighting of search results
No index (probably, JetBrains help does not contain it)
No "Print" button, but permalinks bring you to pages that are ideal for printing.

Notes:

Built with ExtJS.

Summary: very good, especially for API references. Good UX, as at the whole JetBrains' web site.

ComponentOne NetHelp
URL: http://helpcentral.componentone.com/Documentation.aspx - for all C1 products

Nice features:

"Previous page" and "Next page" buttons available at toolbar.

Issues:

Top frame URL does not change. It seems there is no way to get link to current page.
TOC, keyword and search indexes are fully loaded into the browser on navigation to corresponding tabs.
Most likely, search is implemented in JavaScript.

Summary: visually better than Autodesk Online Help, but UX is very similar.

Oracle Help Technologies

URL: http://www.oracle.com/technology/tech/java/help/index.html - there is a link to demo.

Nice features:

All the features I expect to see (based on e.g. MSDN library experience) are available there.

Issues:

No good URLs, but there are permalinks.

Notes:

Animation of left pane is slooow... Completely unclear, why they use it at all there.
Design must be improved (my own opinion = very subjective).

Resume: one of the most featured help browser among the others. The only lacks I'd list is its design & slow animation.

Eclipse Documentation
URL: http://help.eclipse.org/galileo/index.jsp

Nice features:

All the features I expect to see are available there.
Good search results (with quotations).

Issues:

No URLs, no permalinks.

Notes:

Index search returns paged results. Looks a bit strange from the point of UX.
Really ancient design.

Resume: one of the most featured help browser among others here, although I think its design must be improved as well.

Mono Documentation
URL: http://www.go-mono.com/docs/index.aspx

Nice features:

AJAX TOC
It works noticeably faster than other help browsers - at least, from our office. Most likely, they properly tuned up content caching headers there.

Issues:

No search
No index
No URLs
Clicking on "permalink" closes all the nodes in TOC
1px splitter - I noticed it only by occasion :)

Resume: search feature must definitely be added there. Generally, it must be better, since Mono is positioned as free alternative to Microsoft .NET. The only fact partially "saving" them now is that people can use Microsoft .NET help instead of this one (although Mono has a set of unique assemblies).

Other examples:

PHP Help: http://www.php.net/manual/en/
MySQL Help: http://dev.mysql.com/doc/refman/5.5/en/
Maple Help: http://www.maplesoft.com/support/help/AddOns/view.aspx?path=MaplePortal

Online help browsers available on the market

This part contains just a list of them: usually product web site provides all the necessary information (supported features, browsers, etc.).

Supported help formats (.CHM, .HxS, etc.) and server platforms are mentioned here. Products are listed alphabetically.

A!K Research Labs chm2web
Product page: http://chm2web.aklabs.com/
Online demo: http://chm2web.aklabs.com/helpfr/

Supported help file formats: .CHM
Supported server platform: any (generated web sites use only HTML and JavaScript).

Herd Software Development WinhelpCGI
Product page: http://www.herdsoft.com/linux/produkte/winhelpcgi.html
Online demo: http://www.herdsoft.com/ti/winhelpcgi/

Supported help file formats: WinHelp (.HLP)

Supported server platform: Linux, web server with CGI support is required.

Oracle Help Technologies
URL: http://www.oracle.com/technology/tech/java/help/index.html - there is a link to demo.

This tool was described above.

Supported help file formats: Oracle Help

Supported server platform: cross-platform (viewer is implemented in Java),

X-tensive.com Help Server

Product page: http://www.x-tensive.com/Products/HS/

Online demo: http://help.x-tensive.com/

Supported help file formats: Microsoft Help 1.x (.CHM) and 2.x (.HxS), plain HTML
Supported server platform: Windows, IIS 6.0/7.0 with ASP.NET 3.5.

Help authoring/generation tools supporting web help (website) output

Tools listed below are capable to generate web site from help project. They do not support standard help formats, but if you're building a documentation using one of these tools, it can can be converted to a website exposing it on the web.

Adobe RoboHelp
Product page: http://www.adobe.com/products/robohelp/

There are two ways of building web-based documentation in RoboHelp:

Using FlashHelp output format. An example is here (official).
Using WebHelp output format. An example is here (not official - unfortunately, I was unable to find an official one at Adobe.com, so I took one from this list).

ComponentOne NetHelp in Doc2Help

Product page: http://www.componentone.com/SuperProducts/DocToHelp/

Web help example: http://helpcentral.componentone.com/Documentation.aspx

This tool was described above.

Supported server platform: any (generated web sites use only HTML and JavaScript).

ExtremeEase HelpConsole

Product page: http://www.extremeease.com/HelpConsole_2008_Overview.htm

Web help example: http://www.extremeease.com/help/demo%20help%20system/default.aspx

Supported server platform: any (generated web sites use only HTML and JavaScript).

Helixoft VSdocman and VBdocman

Product page: http://www.helixoft.com/vsdocman/overview.html

Web help example: http://www.helixoft.com/images/stories/vsdocman/help/

Supported server platform: any (generated web sites use only HTML and JavaScript).

Microsoft Sandcastle

Product page: http://www.codeplex.com/Sandcastle

Sandcastle is general purpose documentation generator using XML comments in C# \ VB.NET files to build it. There are two ways of building web-based documentation using it:

Using DocSite Templates for Docproject. Example output screenshots are here (I couldn't find real web site, so there are just screenshots). Generated web site requires IIS 6.0 with ASP.NET 2.0 to run.
Using Sandcastle Website output. Examples of such documentation: first, second, third (not official, Sandcastle authors currently don't maintain official example site).