I was at a meeting in Ayr on Thursday. When it finished I just wanted to get home as quickly as possible (Ayr to Edinburgh is about 83 miles).

Naturally, as is my habit, I took the first available wrong turn and very soon found myself driving around an unfamiliar Scottish seaside town in the rain.

This is why I need sat nav. And it struck me, as I was stuck at yet another set of traffic lights, that context-sensitive online help in a software application is like sat nav in a car.

You never notice how badly signposted towns are until you're lost. Then it becomes painfully obvious just how often streets don't have a street sign on them, and how road signs tell you your destination is in one direction at one junction but when you come to the next junction the destination isn't mentioned and you're left to make your best guess. Signs are often only designed for locals - so they indicate how to get to places a few miles away, but they're no use if you want to get out of town and go somewhere else.

This is like software. Poorly designed software is difficult to navigate and often only takes into account the most likely use cases. If you're doing anything even slightly out of the usual, then you're own your own mate!

Without sat nav, when you get lost, you can generally do one of two things:

1. Ask an expert
   This involves stopping the car and either asking a local, or (usually more reliable) phoning your nearest and dearest and asking him/her to look up Google Maps and work out directions for you.
2. Look up a map
   Again you've got to stop the car. You've also got to keep a road atlas in the car. And you've got to rely on it being up to date.

The software equivalent of 1, without online help in an application, is asking a colleague to help you out. This takes you away from your computer, interrupts someone else's work and requires a patient local expert. There's only so many times you can use this workaround before it gets very irritating for everybody.

The software equivalent of 2 is reading the printed manual. This assumes there is one and it's up to date. Again it disrupts the flow of your work within the application (like stopping the car to dig out the map).

Other similarities between context-sensitive help and sat nav are:

• It should be available when you want it.
• It's got to give you correct information.
• It should tell you only what you need to know.
  Verbose online help is about as irritating as a sat nav that keeps telling you to "continue straight on" rather than shutting up until it's time to turn.

Anyway, to finish, here's a Sunday-best picture of Ayr (it wasn't looking like this on Thursday).

Don’t you just hate it when software tries to be helpful but just gets in the way?

I’m currently working on tidying up a migration of RoboHelp into Flare. I’ve got to say immediately that Flare does an excellent job of migrating RoboHelp projects – but only if you’ve only used RoboHelp from within it’s GUI and never gone and tinkered with the HTML or added your own Javascript.

Huh! What are the chances of that?

Any help project from a few years ago that was built in RoboHelp will definitely and certainly have some tweaking and augmenting to it – or it will look like rubbish and be clunky and unsophisticated. Things might be different in the current version of RoboHelp, I don’t know, I don’t have it – but previous versions of RoboHelp had some serious shortcomings that forced you into a bit of roll-your-own behaviour just in order to get things looking and working the way you wanted.

The trouble is, once you do a migration into Flare, none of this is handled for you. I’m not complaining about that. The guys at Madcap have no way of knowing what extra goodness you layered on top of your plain old RoboHelp projects. And fortunately, most of the time, Flare just leaves any stuff you added by hand. That way you can do what I’ve been doing over the past few days: you can run some crafty regex search/replaces to go and convert those things into something that’ll work in Flare.

Unfortunately though, the philosophy of “if you don’t understand it, don’t touch it” hasn’t been extended to the TOC processing. The TOCs in the projects I’ve been migrating use anchor names at the end of topic file names, to pass a value to a redirect file, which then sends the browser off to display the appropriate page. Why would you want to do that then, I hear you ask. Well it’s a nice little Rob Chandler trick that allows you to decide which entry in the TOC gets highlighted where there are multiple TOC refs to the same topic. If you don’t use this method, the TOC will always jump to the first reference to the topic.

After some laborious debugging I’ve discovered that, at build time, Flare is taking my TOC file, seeing references such as redirect.file#sometopic and stripping off the anchor. So, within the generated .chm the reference is just redirect.file, which results in no redirection happening because the Javascript never finds out where to redirect to.

Flare does the same with query strings, like redirect.file?param=value. Annoying! Very annoying! It’s like when you were a kid and your mother tidied up your bedroom and chucked out your favourite comic. “Well it was lying on the floor. How was I to know it was important?”

In this interview, from Channel 9, April Reagan (a Program Manager at Microsoft) talks about the up-coming Microsoft Help 3. This client-side help system will be used first in the MSDN Library within Visual Studio 2010, but will be made available for other software companies to use.

Note: I found the first half of the video the most interesting. After that the interview moves onto other things and only returns to help towards the end. Unfortunately there’s not a whole lot of detail about how the new help system will differ from good old HTML Help. There’s no demo, for instance. Still it’s interesting that Microsoft are still investing in the idea of client-side help.

Note: This video belongs to Dan Fernandez and Channel 9.
If you're having problems viewing the above video, try the orignal video on Channel 9,
or view it in Windows Media Player.

I posted the following question on the Content Wrangler forum yesterday, but returning to it today I notice that most of the other posts to the forum get zero responses, so I’m going to repeat this appeal for ideas here, and I’ll try and think of other places I might pose the question.

I'm hoping for some advice on a way to provide server-based online help. The trouble is it can't be Web-based. Does anyone know of something out there that would solve this problem?

We've got a client/server software application that needs user assistance. It can't be traditional client-side HTML Help because this leaves help files on the PC, which not good for us because of the confidential nature of parts of the IT system. For a similar reason (plus some technical reasons) it can't be Web help.

What I'm looking for is a help viewer that will be launched from within a client application but which will fetch it's help topics from the same secure server used by other parts of the application. The help viewer can be located on the client side, but the help topics must be pulled down from the server.

I have had a look at Adobe AIR Help, but this seems to download files to the client and leave them there for use next time, which is no good for our purposes. I have also had a look at Madcap Flare's .NET Help, but I think this is also client-side, plus Madcap supplies very little information about .NET Help which worries me because I'd rather not migrate to a system/method that is poorly documented (unlike HTML Help or Webhelp output from Flare, which is well documented).

So I'm looking for ideas. Am I missing something obvious? Can anyone suggest a solution? Please post a comment below.

This is an old tip (see Viewing dynamic HTML in a .chm topic from March 2004) but worth knowing.

Suppose you have some JavaScript in a help topic that alters the HTML of the page - for example, it might do some transformations onLoad, or it might be doing AJAX-type stuff in response to input from the user). To debug the JavaScript you need to be able to check the HTML to make sure the transformations are occurring as designed. Right-clicking and choosing View Source is no good because you only see the original HTML saved in the file, before any transformations happened.

To see the dynamically generated HTML as it is right now:

1. Copy the following:

   javascript:window.open("").document.open("text/plain", "").write(document.documentElement.outerHTML);

2. Right-click the title bar of the HTML Help Viewer.
3. Choose Jump to URL.

   

4. In the Jump to URL dialog box, paste the text you copied in step 1.

    

   The HTML is displayed in a new Internet Explorer window.