Replacing the Microsoft HTML (.chm) format

[dtmenges]

We have used the Microsoft HTML .chm for help for the last several years are in the process of defining new products. I told the project managers and developers that we need to change help formats to stay current and avoid the problems we had when Microsoft Help died with XP. I support eight titles all of which require PDF and help with help being the primary delivery method.

• Three of our eight software titles are in
  • .Net
  • One title is a bunch of Java files. This one does not have help, only PDF
  • The rest are C++ and Turbo Pascal.
  • The .NET titles do not have any context sensitive help, just help, index and TOC from the titlebar.

Looking to the future, what would be suitable help formats? I would lean toward .NET and Web Help. Any thoughs or suggestions.

[RamonS]

I always was an advocate for WebHelp. DotNetHelp is nice, but you will be trading one proprietary format for another with the additional baggage of needing to deliver a specialized reader and likely causing more development work to be necessary compared to using WebHelp. Although in all fairness, it should amount to rewriting the help module that should be used across one application keeping the individual calls the same assuming that they do nothing more than pass in a map ID.
WebHelp would be a format that works with all applications and is as easy to implement as is making a call to a URL.

One word of warning, switching away from CHM to any other format will not make all problems go away. Some will be resolved, some will stay (such as those problems introduced by varying IE security settings, which are in effect for other browsers as well), and some will be added. It all depends if the final collection of problems is easier to manage or less of an annoyance.
I'd pilot the smallest app / smallest help using WebHelp and see how that works out for you. Keep in mind that WebHelp can run locally and does not need a web server.

[LTinker68]

DotNetHelp is nice, but you will be trading one proprietary format for another with the additional baggage of needing to deliver a specialized reader and likely causing more development work to be necessary compared to using WebHelp...

However, the DotNetHelp has an SDK that allows you to integrate the help into your application like Flare's internal help is integrated into the Flare GUI, if your application is .NET-based. You should double-check about that and research it a bit to confirm, but I believe it has that capability.

[Robotman]

I'd read the posts on the .Net Flare forums before making a decision.

http://forums.madcapsoftware.com/viewforum.php?f=7

Our company stills wants to move to .Net for our help but we don't think Flare is 100% ready so we've opted for webhelp as a replacement for CHM.

[dtmenges]

Thanks for the feedback. Not sure which way to go for the dot.NET programs but at least I can make an informed decision.

[i-tietz]

I always was an advocate for WebHelp. DotNetHelp is nice, but you will be trading one proprietary format for another with the additional baggage of needing to deliver a specialized reader and likely causing more development work to be necessary compared to using WebHelp.
...
WebHelp would be a format that works with all applications and is as easy to implement as is making a call to a URL.
...
One word of warning, switching away from CHM to any other format will not make all problems go away. Some will be resolved, some will stay (such as those problems introduced by varying IE security settings, which are in effect for other browsers as well), and some will be added. It all depends if the final collection of problems is easier to manage or less of an annoyance.

I suppose you never developed websites or Webhelp?
With each new version of each browser the checking starts: Each website in each situation in that new browser version. And eventually you have to adapt and if you do you will have to check in all other browsers and versions all over again. Or will you simply wait for the next release (bugfix)? Will the customers wait or will they call in and complain that that and that and that doesn't work anymore? There are some recent threads about exactly those problems.
So: To say that Webhelp means less work is pretty lightheaded ...
I would easily prefer to do the programming once only and before delivery, cos' the chance for a controlled environment is a lot higher that way.

And with software it's definitely no problem to install a help viewer. And for the PDFs we're delivering we also offer installing the Reader - just in case the user hasn't got it. Does that mean we're not supposed to deliver PDFs? Checking (and adapting to) one software package is far easier and quicker than checking (and adapting to) a handful.

[RamonS]

I never claimed that WebHelp is less work, not sure where you got that from. What I wrote is that WebHelp will come with a different set of issues and it depends if that set of issues is easier to manage than the problems that come with CHM.
As far as the differences in browsers are concerned, no matter what you do, pages will look different in the various browsers and various OS. With that I yet have to come across a browser that fails to display WebHelp assuming that the security settings are configured in such a way that viewing WebHelp is possible. It will not look exactly the same, but it is still usable. I find it pointless in chasing down the differences and tweaking page content to make it look and feel identical in each browser, it is impossible. So why do it?
As far as my development of web pages is concerned, experience tells me that less is more. Why do you think that sites like Craigslist are doing well. It is bare bones and no frills and the users don't mind it a bit. In fact, they like it that way.

[i-tietz]

... and likely causing more development work to be necessary compared to using WebHelp

[i-tietz]

I never claimed that WebHelp is less work, not sure where you got that from. What I wrote is that WebHelp will come with a different set of issues and it depends if that set of issues is easier to manage than the problems that come with CHM.
As far as the differences in browsers are concerned, no matter what you do, pages will look different in the various browsers and various OS. With that I yet have to come across a browser that fails to display WebHelp assuming that the security settings are configured in such a way that viewing WebHelp is possible. It will not look exactly the same, but it is still usable. I find it pointless in chasing down the differences and tweaking page content to make it look and feel identical in each browser, it is impossible. So why do it?
As far as my development of web pages is concerned, experience tells me that less is more. Why do you think that sites like Craigslist are doing well. It is bare bones and no frills and the users don't mind it a bit. In fact, they like it that way.

Simple.Aha.
And what about popups? And what about non-scrolling headers and footers? And what about "I want the dropdown to be open onload"? And what about simulating the tripane look by using divs, maybe even non-scrolling ones? What about jumping to bookmarks in a topic when you have a non-scrolling header? And what about using your own search facility? ...
All these are issues I saw on these forums not really long ago ...

Welcome to the real world! (*quote from "Matrix")
Even if we don't like it: Users want the looks and functions they're used to from all the other software they use. And almost always you cannot get there by going "simple".
It's a nice theory though ... sigh ...

[RamonS]

Yes, for DotNetHelp there is likely more work, because the developers need to implement the code from the SDK and the integrated browser rather than using stock functions for calling a URL. Implementing DotNetHelp is more work than simply making a URL call.

[RamonS]

Even if we don't like it: Users want the looks and functions they're used to from all the other software they use. And almost always you cannot get there by going "simple".
It's a nice theory though ... sigh ...

But users are fine with CHM. How much more bare bones and boring can it get?

[i-tietz]

But users are fine with CHM. How much more bare bones and boring can it get?

HTML Helps can be very complex ... and getting a nice outfit and more complex functions is easier than in WebHelp because it's programming for IE only ...

[i-tietz]

Yes, for DotNetHelp there is likely more work, because the developers need to implement the code from the SDK and the integrated browser rather than using stock functions for calling a URL. Implementing DotNetHelp is more work than simply making a URL call.

That's for developers. And what about those people who produce the help?
If you use javascript and CSS it's a permanent gamble. And Flare uses A LOT OF javascript (toolbar, quick search, dropdowns, popups, glossary terms, ... )!

[NorthEast]

We've had Flare's WebHelp in our products for about 4 years now, and we've had no major problems so far. To date, I've not yet had to make a single change to our own CSS/code to make it work with a new version of a browser.

For me, the main risk with WebHelp is being reliant on MadCap to test and fix issues in their code; a good example was when they had to fix WebHelp to work with Chrome. To date though, MadCap do tend to fix and release new versions quite quickly (compared to most companies).

[i-tietz]

True. Pretty fast.
But just wait for the moment when MC follows the wishes of some of you and skips the tripane approach and goes for divs to position all those elements (toolbar, TOC, ... ) ... Then you will notice how different interpretation of positions, margins, paddings, floats, clears and all sorts of other styles will be in different browsers ...