It would appear that CHM help files are no longer the help file format of choice.

- obsolete

HtmlHelp (CHM)
- not supported on Vista by default
- does not work well on a network share

Help 2 (HXS)
- I understand this is used in VS2005+ for displaying help

Web Based
- Could be hard to manage for multiple versions

What help file format would you use in a new (C#) application that provides multiple versions from the same codebase?

We would like to use CHM help however it doesn't appear to be the direction that Microsoft wants us to move in.

Does anyone employ HXS for their help files?

Feeback appreciated

Update based upon lassevk comments;

Looks as though HXS help is not intended to be used for normal help projects.

+3  A: 
this.Mode = Modes.Rant;

There are tremendous problems with almost all the help file formats because the makers (typically Microsoft for quite a few of them) doesn't seem to want to do a job more than just slightly good enough for their own use.

I can't tell you how many times the new HXS format has completely hosed my Visual Studio help when 3rd parties integrate. You could say this is the fault of the third party installation tools, but for quite some time there was no documentation on how to do this, so they had to chose between reverse engineering it (and getting it wrong, sometimes) or not integrating at all. I still don't know if the integration works, but these days I just switch Visual Studio to use online help. It just works, mostly, whereas the built-in help invariably falls down to that progress bar that just locks Visual Studio until it has rebuilt the help file, except that it didn't because the files are now corrupt, so any time I hit F1, Visual Studio just locks down unless I kill the DEXPLORE program any number of times.

How this ended up as a solution to any problem, I still don't know.

Secondly, the tools needs to be present. CHM viewer is present on pre-vista, not on Vista, but the tools needed to show HXS isn't present on pre-vista, but I gather they are on Vista. Nice, so now I have a choice between using one format that needs to be custom-installed on the users computer, or ... err, another one that needs to be custom-installed on other users computers. Right.

this.Mode = Modes.JustTicked;

Where I work we ship CHM files, and a file-based html version for those that deploy their applications through a network share. As for Vista, we haven't seen much of that yet, but the html version would work there too.

I'd much rather have a shiny help file though.

One nice upshot of html version is that we can link in the same files in the web module that follows our product. This way there would be only one version that customer needs.

We're looking at upgrading the tool we use at work so on my schedule for this week, nice and quiet at work, I will be looking at the various types of output it can produce, amongst other things HXS.

Edit: Hmm, a quick look at the help pages for Help and Manual, the product we use, has this to say about HXS:

Visual Studio Help is also known as MS Help 2.0. Originally this help format was intended to be the successor to HTML Help. However, Microsoft then postponed its release indefinitely and it is now clear that it is never going to be released as a help format for normal user applications.

Please note that this is a special help format that is only used for documenting third-party programming components designed for integration into Visual Studio .NET. It is not suitable for any other purpose and cannot be used for normal help projects for application programs!

I guess HXS is completely off the table then.

Note: Web-based wouldn't necessarily mean that you need a web server, only that you need a web browser. Whether you integrate it into your app, using a web browser component, or if you just launch the users default browser, that would be a choice you would have to make, but most web-based help outputs I've seen does not require any server setup at all.

Lasse V. Karlsen
thanks ... looks like HXS is totally off limits.
Maybe we just have to wait for Windows 7 to find out what they're going to do there. And then, again, in Windows 8. ... :D
Jonathan Leffler

For me, CHM is still the answer. I build CHM files with the Sandcastle Help File Builder tool that is available on Codeplex.

The concerns about the accessibility of CHM are valid. To address that, I produced a CHM-to-Web converter pretty easily, with some IStorage hacking, a text search-and-replace, and an XSL transform. This page is a web site that was produced automatically in about 8 seconds. It has an expand/collapse treeview on the left-hand-side nav. Frames based (not very URL friendly) but it works well enough.

+1  A: 

The only useful help documentation I've ever seen has been plain HTML. Most, if not all, of the open-source projects I've seen all have HTML help pages (for APIs and reference docs). Anything that uses a proprietary format or that requires a proprietary reader all run the risk of going obsolete (CHM), or having compatibility or bloat problems (PDFs).

For some reason, Microsoft is just bad at help files. The online help for Visual Studio/SQL Studio/Office is terrible, MSDN is a mess, CHMs are clunky, and the Microsoft search never returns the results you really want. (Just my opinion :)

Andy White
CHM's are just HTML that is indexed and compressed. There are Open Source viewers and (de)compressors
Marco van de Voort

Adobe RoboHelp can be used to author help content that has content/index/search/glossary and works in a browser as is HTML-generated. Supports 35 languages.

We have a Flex-based web app that uses this for managing the app's help content. The Flex app and its help system work on most browsers on Windows/MacOSX/Linux.

+1  A: 

What exactly makes you think there's no default .chm viewer on windows Vista ? (There certainly is one on my computer, as well as on my Win7 box)

You might confuse .chm with .hlp (Microsoft indeed dropped .hlp support in vista, then eventually resumed it in a windows update)

Bottom line : .chm files seem to be still supported on all windows version, and the only real alternative to .chm files i know of is .html


Some updated thoughts for anyone still reading this question...

According to Wikipedia, Microsoft decided on Microsoft Assistance Markup Language after giving up an Help 2.

There is also Microsoft Help System, which is what ships with Visual Studio 2010.

Colin Pickard