Ask HN: What is the current stable help generation system for Windows? | Hacker News Reader

Ask HN: What is the current stable help generation system for Windows?

13 pointsluch8 comments

I have a fairly technical question for the HN community, hoping some Windows devs would have the answer.

I'm currently writing documentation for a module I developed on Windows, and the question of migrating our large help base was raised. We are currently still using WinHelp, which exists since the beginning of Microsoft, to generate our offline help and it has became increasingly painful to build the help file (restrictions on txt formats, size, lack of native support in Windows 7).

-WinHelp (1990-2006) Our current help engine. Deprecated for almost ten years, yet still functionnal. However it needs more and more hacks in order to make it work. On win7 you also need certains specials KB patches to view the help files. files : hpj, cnt, hlp

-Microsoft Compiled HTML Help (1997-2003) Successor to Microsoft WinHelp and still supported in Windows 7. It look like to me it's the current standard help system, however it's been also deprecated for 10 years. files: chm

-Microsoft Help 2(2001-2009) Help engine used in Microsoft Visual Studio 2002/2003/2005/2008 and Office 2007. Also deprecated. files: .hxs, .hxc, .hxk

-Microsoft Help System(2008-) Latest evolution of offline help system (used in VS 2010). May or may not be a standard. There is little documentation on it anyway. files: I don't even managed to find the input file extension needed.

As I see it, compiled HTML help files seemed to be the way to go, but I'm not sure migrate our help to a deprecated system is the right move. I've skimmed the Windows SDK looking for help files, but it's not coherent (some uses hlp+cnt, others chm, etc.). We are a pure Microsoft-only software team, so I'm not looking for a third-party help generator (like Sphinx or APIDoc).

Is there anyone which could give me some pointers as what would be the current native help system on Windows ?

All Windows Help files ultimately are are a loose wrapper around Trident's HTML rendering engine.

So why not avoid the needless complexity and simply just open up the default browser and point it at a file:// location on the hard drive which corresponds to the index page which then uses relative URLs (and relative images) to open up sub-pages? Essentially a web server-less help system.

Doing it this way has the following advantages:

- The entire help system remains "offline."

- You can however link to "online" articles/content/etc.

- You can host exactly the same help files using a web-server, and they will work perfectly (because they use relative URLs).

- You can give the user the option of the offline one shipped with the software, or one you host which is updated.

Windows' Help system has a bunch of downsides. Using a subset of HTML (i.e. stuff that works in IE7) has few to no downsides, and at this point there is a real expectation that an end user will have a web-browser installed.

In Visual Studio 2013, when I click "View Help" it just opens up a web-page. I cannot see why anyone would do anything else at this stage, offline help doesn't even really change that, I'd still use HTML and a browser.

We're delivering CHM now and migrating to shipping folders with plain-old-HTML. Customers get the same content locally when they press F1 as they would if they found the documentation online.

Note that if you ship HTML files onto the user's hard drive you may have to implement Marks of the Web on each page so the page is rendered as part of the "internet zone". If you don't, certain javascript features (namely AJAX requests) are disabled as they could be a security risk. Alternatively, ship a small webserver to handle the AJAX requests.

More info: http://msdn.microsoft.com/en-us/library/ms537628%28v=vs.85%2...

We're using Sandcastle Help File Builder (SHFB) with great success for generating HTML help files.

https://github.com/EWSoftware/SHFB

I also used Sandcastle. We did a major migration to it in about 2010 (from a 3rd party MSHelp generator application -- I'm blanking on the name, which is a good thing, because I would only tell you to stay away from them)

Never tried it, but Rick Strahl's West Wind company make a MS Help building tool. He's been working on it for years so should be fairly stable:

http://west-wind.com/wwHelp/

The only drawback for you might be the price, but you can download a fully functioning free version to give it a spin.

http://west-wind.com/wwHelp/download.aspx

Put it on the web

No, don't put it on the web! If there's one thing I hate about Microsoft's recent help solutions, it's that they're constantly checking the web when you search for something. Even if what you want is loaded locally and instantly available, you end up waiting while it diddles about.

I am using Markdown to HTML to CHM.

Reply on news.ycombinator.com