The problem

The problem we’re trying to solve is how to debug a topic in a CHM file where you’ve got JavaScript that dynamically changes the HTML at runtime (i.e. when the topic is displayed in the Microsoft HTML Help viewer). If you’re debugging issues in WebHelp output you have the fabulous Firebug plugin that allows you (amongst other things) to click on objects in the output page and see what their HTML looks like right now. But unfortunately you can’t add Firebug to the help viewer. Or can you?

Online solution

This is the best solution, but it relies on you having:

• Internet access
• JavaScript enabled (a safe assumption as it’s probably JavaScript you’re debugging here)
• No firewall settings that might block code being downloaded from getfirebug.com (unlikely)

If any of the above aren’t true then you’ll need to use the offline solution (below).

The online solution uses the Firebug Lite bookmarklet to add much of the functionality of the Firebug plugin for Firefox to the browser pane within the HTML Help Viewer.

1. Do one of the following (these are just alternative ways of copying the same JavaScript to the clipboard): 

   Either: Right-click this link – Firebug Lite – and copy the link location (“Copy Shortcut” in IE).

   Or: Copy the following code:

   javascript:(function(F,i,r,e,b,u,g,L,I,T,E){if(F.getElementById(b))return;E=F[i+'NS']&&F.documentElement.namespaceURI;E=E?F[i+'NS'](E,'script'):F[i]('script');E[r]('id',b);E[r]('src',I+g+T);E[r](b,u);(F[e]('head')[0]||F[e]('body')[0]).appendChild(E);E=new%20Image;E[r]('src',I+L);})(document,'createElement','setAttribute','getElementsByTagName','FirebugLite','4','firebug-lite.js','releases/lite/latest/skin/xp/sprite.png','https://getfirebug.com/','#startOpened');

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.

   

5. Click OK.

   After a moment (while it downloads files) the Firebug panes are displayed across the bottom of the browser pane in the HTML Help viewer.

6. Click Inspect, then click an object in the topic pane.

   The HTML for this object (including any dynamic modifications) is displayed in the HTML tab of the main Firebug pane:

   

Note: External JavaScript and CSS files aren’t recognised because they reside at another domain. So, when you click the CSS tab all you’ll see it “There are no rules in this stylesheet” and in the Script tab you’ll get “Access to restricted URI denied”. However, the functionality of the HTML tab is enough to make this technique extremely valuable for debugging.

Offline solution

The alternative is just to display the current, dynamically modified HTML in the browser pane. You can then select and copy/paste it into an editor for debugging.

To do this, copy and paste the following JavaScript into the Jump to URL dialog box:

javascript:'<xmp>'+window.document.documentElement.outerHTML+'</xmp>';

Note: The xmp element is deprecated and you shouldn't generally use it. However, in this case we know that we're using it in IE (the browser part of the HTML Help viewer) and IE, as of writing, still supports this element. If this stops being the case in future, the following is a less elegant (but standards-compliant) way of doing the same thing:

javascript:'<pre>'+window.document.documentElement.outerHTML.replace(/</g,'&lt;')+'</pre>';

Almost certainly the issue here is that itcc.dll is not registered. This must be registered on the PC on which the CHM file is compiled. After the CHM has been built, registering itcc.dll has no effect on the existing CHM – the Search tab still won’t work. You need to register itcc.dll and then rebuild the HTML Help output.

I’ve just run across this problem with Madcap Flare 6.1, but this is not a Flare problem. itcc.dll is Microsoft’s HTML Help Workshop, an old, old Microsoft DLL that Flare uses when compiling the CHM file. If this DLL wasn’t registered successfully by the Flare installer, or if it gets unregistered (which seems to happen now and again for no apparent reason), then you need to register it manually.

To register itcc.dll in Windows Vista or Windows 7:

1. In the search box at the bottom of the Windows start menu, type cmd.
2. In the result list, right-click cmd.exe and choose Run as administrator.

   Note: This is important. If you have Windows UAC enabled (you should!), then you won’t be able to register the DLL unless you do so as an administrator (even if you’re logged on as a user with administrator privileges).

3. In the command console window, type: regsvr32 itcc.dll and press Enter.

   A message is displayed confirming that the DLL was registered successfully.

   

4. Restart Flare and rebuild the CHM output.

Related post: Fixing Search in Flare HTML Help.

So I happened to be resurrecting an old Yahoo email account this evening and I couldn't resist clicking the Help link to see how Yahoo do their online help. And, lo and behold: a big search box at the top with a well-chosen selection of links below.

It's an email system, so I tried searching for "spam" and I got a very decent set of results:

And clicking on a link took me to a nicely pitched little tutorial topic on avoiding spam:

So the result is that from the help page I just have to do a search and click a link to get straight to some useful help. That's how it should be to get help with something on a computer. Anything more complicated than that has a problem. 

Next, after you've got a decent understanding of the subject matter, you then start looking at the application (what there is of it so far, plus any plans/designs/user stories you can find for what will be appearing in future iterations of work) and you talk to the project managers, developers and testers, and hopefully you also get to talk to some beta users or user advocates.

Then you can begin to plan your help system. What's the top-level structure going to look like? How are you going to break it down into sections and subsections. Several years ago I worked on a help system where we spent weeks drawing up a complete TOC for the help, and getting it reviewed and signed off, before we started writing a single topic. Needless to say, that was long before I'd heard of the Agile development approach.

But my previous couple of posts have got me thinking. If we could do away with the TOC maybe we could do away with any structure outside of individual topics. And if we could do that then we could cut out a lot of the preliminary process outlined above. It might mean we could get to the point of creating useful content much more quickly.

The ScreenSteps approach is worth considering here. It goes something like this:

• At initial release, the help system just contains 10-20 questions that you know users are likely to have
• After release of the software, the help system grows over time as users ask questions and you add the answers to those questions to the help. But note: you only add new content in response to real questions
• New help topics get dropped into the help as you write them. Users can find them in a search and you can send them a link that'll get them straight to that topic. Consumers of the help don't need a TOC.

The ScreenSteps Documentation home page is a great example of a simple documentation interface:

Notice how predominant the search box is. You could claim this page has a table of contents - it kind of does - but it's not like the traditional, elaborate expanding-tree TOCs you find in many online help systems. It's just a simple series of links. If you click one of these links you get to a similar page with more links, from which you go to an actual topic. So there's never more than one hierarchical level of links on screen at once, and you're never more than two clicks from a help topic.

And what I really like is that this allows you to keep adding topics without always having to decide where to place a link in a tree TOC. Just write the topic and get it in there for users to see. If it merits a link in one of the secondary links pages you can go and add one, but I'm pretty sure most people using this system will get to content via a search.

I'm convinced these days the majority of us are searchers rather than looker-uppers. So the search box serves the majority searcher community, and the links are there:

1. For the minority looker-uppers
2. To direct people quickly to popular topics. Hopefully you're able to use the logs from your web server to spot the topics that most people go to and you can design appropriate first and second-level links to get people there fast.

Maybe it's time to retire the old tri-pane online help:

Apologies to ESRI. I'm really not slagging their online help (acually I think it's very good). It's just the first internet-visible tri-pane WebHelp I could think of.

Tom describes helping out with user support for an application. He also works on the online help for this application. He describes how useful this contact with users can be. He writes:

I know that this support role, while annoying at times, is also advantageous because it gives me an insight into the real problems users are having. Through this close connection and user-informed perspective, my help can provide real answers that users want.

Talking to users. Wow! That's how it should work. My own experience, documenting enterprise-level software, is that the tech writers and the end users often never come into contact. Our end users (yes, I know, horrible expression, but what I mean is not the administrative users, or the managers, or the customer’s support staff, and not the decision makers who you sold the system to originally but who will never actually use it, but the people who have to use the software day-in, day-out as part of their jobs) … hang on, let me start that sentence again. Our end users contact their internal support staff and, if they can't help, those support people log a support call with our third-party call centre and it then gets picked up by our support people who generally manage to solve the issue very quickly and without reference to anyone else. The tech writers usually never find out about these support calls unless they take the time to check the support system regularly, or they hang out with the support guys (which tends not to happen just because we're in a different part of the building). So it's not unusual for tech writers to work on a product for months, or years, and never talk to an end user. Their knowledge of the end user tends to come second hand, through the product manager or some other SME. And it just stands to reason that if you had a direct line to your end users your documentation would inevitably be much more fit for purpose, and would get better over time.

So Tom’s post got me thinking: maybe working periodically in support is something all tech writers should do.

Tom’s post also referred to an old ITauthor podcast where Graham and I discussed how much you should document. I must admit I’d completely forgotten about that one. I should probably listen to it again some time.

But what I think I probably said in that podcast, and it’s what I really believe, is that tech writers have to get away from the habit of just bashing on and documenting stuff. Time and time again I've seen tech writers succumb to the temptation to just document whatever they see in the user interface. This is always going to result in pointlessly bloated documentation. It's the scatter-gun approach: "How should I know what users will want to know about? So I'm just going to document as much as possible."

I'm convinced the result is that a lot of time is wasted documenting things that, in a well designed interface, are obvious to the user. Those things tend to be the things users do most of the time: the basic, nuts and bolts operations that were in the original design of the application. The interface makes it easy to figure out how to do those things, so users don't need help with that. It tends to be the secondary things - the stuff that got added to the application in later iterations, and which are accessed via a menu item rather than being immediately obvious - it's those things that users tend to need some help with. But generally, to make the initial help system at least adequate for release, the tech writer needs to do a lot of thinking up front, ask a lot of questions, and get a pretty good understanding of the workflow through the application, and what tasks different sorts of users are trying to complete, and a fairly clear picture of how the application will really be used in day-to-day practice, before he or she starts writing help topics.

Tom’s post and the comments after it talk about how, as a result of users asking questions, and perhaps contributing answers to user forums, a help system can continue to grow and improve. And it’s obviously a good idea: after the initial, good-enough-for-release version of the help, with the assistance of users the user assistance gets better and better over time. In practice I think this is still all too often an aspiration rather than a reality.

Tom, who I’m assuming works on hosted WebHelp, describes how whenever he gets a support question that is now answered in the help, he goes and writes a topic answering the question, rebuilds the help and then replies to the user with a reference to the new topic. I think this is a great idea, but it only works where you host the WebHelp. If your customers host the help on their own server, or if the online help is traditional client-side CHM files, then it can be months before users see the next version of the help system.

One of the comments I really liked was by Larry Kunz. He writes:

As community-based documentation really takes off, I envision users’ requests going into forums (or something similar), and the answers being posted to the same forums - either by you or by other users. If the user community really becomes active, your role evolves into more of a curator (editing user-generated content and tagging it for findability) and less of a content producer.

Is this yet another alternative title for our role: information curator?

After commenting on the post I continued to mull it over, in particular the issue of finding information in a help system that just keeps growing and growing. Tom writes:

in a thoroughly massive help file, it becomes more difficult to find information. If a user expands a TOC to find dozens of subfolders and sub-subfolders and scores of topics within each subfolder, the system of navigation will become intimidating and cumbersome. The user will revert to keyword searches as a primary means of finding searches. After a few fruitless keyword searches without the right results, he or she may simply give up. The easy-to-use navigation system suffocates under the load of help topics

This gave me a radical thought. Isn’t it about time to do away with the TOC and the index in online help systems? Both the table of contents and the index features of printed books that were pulled across into online help, way before Google appeared in our lives, and maybe they’re just not appropriate for online help.

Surely what we need is really good search results. How do 99.9999…% of people find information online? Through a search engine. The more I think about it the more convinced I am that, if your online help had a great search engine, you wouldn’t need to worry about the system growing and growing as questions and feedback from users helped you add the information they wanted to find. Better still would be the situation where a user community forum helped you build into the help the answers to questions people had actually asked, rather than the tech writer’s best guess of what they might ask.

So come on help tool vendors, give us really good search results. The search functionality in Madcap Flare’s WebHelp leaves a lot to be desired - try doing quoted searches. If you publish WebHelp that’s publicly visible, you can use Google as your search engine and, while far from perfect, that’s probably going to give you the best available search results right now. But what if your WebHelp is hosted on an isolated corporate network? Or what if you’re tied to delivering old-style CHM help for the foreseeable future? Back to the help tool vendors in that case. Come on: give us really good search results.

From making a habit of talking to non-technical people about how they figure out how to use software, I’m convinced the majority of people wouldn’t bat an eyelid if the TOC and index disappeared from help system and the landing page for help was just a simple, Google-like page with a box to type in your question and a big old Search button.

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).

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?”

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'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.

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.

Say you make a change to a topic and you just want to check quickly that it'll work correctly within the compiled help. For example, the topic might reference a JavaScript file that only works in the context of the Help Viewer, so if you just open the topic in a browser the page doesn't look and/or behave like it does within the help system. So you need to check it in the help system, but you don't want to recompile the help system.

The solution is simple. Just open the existing .chm file, right-click the title bar and choose Jump to URL.

In the Jump to URL dialog box, enter the path to the file you want to test:
 

Click OK.

The topic is displayed in the Help Viewer just as if you compiled it in there.

So we have a legacy help system (which I created about six years ago and the content of which is mainly still my work) which is supplemented by context-sensitive help (CSH) for each solution. One of my tasks for the coming months is to make sure that the topics in the core help system work equally well in the context of each solution. The tricky bit is that these solutions are designed to be integrated, so while one customer may only have Solution B, another customer may have Solutions A, B and C all integrated together within the same system, with some of their users only getting access to one solution, but others seeing all three. And the help topics need to allow for this without: a) requiring any coding (because no development effort is available for user assistance) or b) turning into a maintenance nightmare by creating a web of conditional behaviour.

But thinking about how this might be done led me to consider how important this core help system is. And in my opinion, from the user's point of view, the importance of assistance is largely measured in relation to how immediate it is. This is, of course, balanced by how useful it is and the nature of the assistance they need, but number of clicks away from where I am now is a big factor. So it shapes up like so:

1. What's in the user interface (labelling and messages).

2. What the user sees first when they click Help.

3. What they see next.

4. If they're still looking, what they see next.

Tech writers don't get involved enough with point 1 (Graham and I were just discussing this yesterday). It's something we could really help out with but are rarely asked to contribute to. Now I'm not saying that a good tech writer is necessarily a good usability analyst, but I know from experience that we're often more sensitive to usability than the programmers who often get left to write user interface text.

Point 2 might be a CSH topic with the information the user needs, but sometimes (e.g. when there are lots of things you might be doing on that particular dialog box or form) it's not possible to cover all the bases in a short, snappy help topic, so you need to use a landing page topic with questions that will branch out into information topics.

Point 3 is either a topic within the help system (if 2 was a CSH topic) or a CSH topic (if 2 was a landing page).

Point 4  is a topic within the help system, and because it's so far removed from what the user was looking at, he/she may never get here. Help is all about getting an answer and getting on with what you were doing as quickly as possible. Nobody but a really desperate user - or a tech writer - browses a help system.

So I think we need to really focus our attention on the context-sensitive help: the CSH information topics and any landing page topics we need to use. Yes, we should try to make the core help system as comprehensive in its coverage as we think genuinely represents value for money and a good use of our time/effort, but I believe we should only do this after we're happy that we've made a really good job of the CSH.

I guess it's the tyranny of the majority again. We're spending a lot of effort crafting really well targeted, clear, concise and correct topics for the majority of users who never get past one or maybe two clicks into the help. And inevitably, in doing so, we're going to have to sacrifice some of the requirements of the minority of users who occasionally go looking for information in the core help system. For them, I believe, we should concentrate in getting the information in there for them. It might not be pretty. We might not have spent so long crafting it to be easy to digest. But it's better to have information in there that you have to read twice to work out what it means, than not to have the information in there at all. We can comfort ourselves, perhaps, with the thought that users who are prepared to go digging in the help system may be more capable of understanding information that might be a little bit raw.

This is thanks to a stunning piece of incompetence on Microsoft’s part. They managed to break the hhctrl.ocx Active X file that controls the related topics popups. After about version 4.7 of this file, related topics always appear in a dialog box unless the language of your project is set to US English.

The workaround for RoboHelp is to open the .hhp file in a text editor (e.g. UltraEdit) and make sure the Language is set as follows in the [OPTIONS] section of the file:

Language=0x409 English (United States)

The chances are there won’t be a Language setting, in which case just add this. Save the file and, when you next compile the project, the related topics are displayed as popups.

If you've imported your RoboHelp project into Flare, go into Project > Project Settings and make sure the language is set to English (United States), then recompile the .chm file.

http://webhelp.esri.com/arcgisdesktop/9.2/index.cf...

I particularly like how they've done the Print/Email/Feedback links in the title box for each topic, and the way they've done Related Topics.

Some really good ideas and a nice design. I wish I'd seen this a few months back before I got so far down the road with the WebHelp I'm currently working on.

Anyway, while searching Google for an answer I came across this article about RoboHelp in a blog by someone called Ryan:

www.youknowwhatpart.com/archives/2005/03/productivity_to.html

It's an interesting blog and I spent a bit of time there, but it left me wondering: who is this guy? How come he knows about RoboHelp and Madcap and Framemaker? Is he a technical writer? The blog gives nothing away. The "View my profile" link goes to a blank entry on Technorati.

But then I thought, my blog probably says nothing about who I am either!

www.madcapsoftware.com/products/demos.asp#

I didn't think much of the first one (see Disappointing MadCap Flare demo) but this demo is more interesting. It shows a RoboHelp X5 project being imported into Flare.

I find it quite amusing how much emphasis MadCap place on the fact that some of their guys used to work on RoboHelp at eHelp. OK, you've told us already! We get it! Your whole business plan is predicated on RoboHelp users switching to Flare. Fine. Let's see if MadCap can deliver on their promises.

www.winwriters.com/articles/rh/

This works fine when you access the Web-based Help directly off the file system (e.g. \\servername\path\to\WebHelp\index.htm), but it didn't work when the same files was accessed over HTTP (e.g. http://www.domain.xyz/path/to/WebHelp/index.htm) and I couldn't work out why.

The solution is something to do with asynchronous loading (the page loads before the ActiveX control - or something like that). Anyhow, whatever the precise reason, the solution is to turn off asynchronous loading. You do this by adding one line to your JavaScript.

So, for me, immediately after the line:

mx_xmlDoc = new ActiveXObject("Microsoft.XMLDOM");

I added:

mx_xmlDoc.async=false;

and this solved the problem.

When I first heard about MadCap back in March I thought it sounded very promising. With the slow death of FrameMaker and an extremely uncertain future for RoboHelp, the time is surely right for someone to arrive on the scene and produce a killer app for technical assistance. MadCap Flare sounded promising.

However, things have been very quiet, so I was pleased to hear about the demo and I went straight to have a look at it, eager to see how far along they'd got.

Unfortunately, the demo is not encouraging. It sticks to the user interface, which is ... well, a user interface. You seen one GUI these days, you pretty much seem 'em all.

What I wanted to know is what MadCap Flare can do. Is it the application I need to write MAML-based help for Windows Vista? Will it be the single source solution I've been searching for to allow me to produce application User Assistance and printed documentation from the same text? Who knows?

All MadCap are saying is: it'll be great, it'll be just what you need, you can switch from RoboHelp, it's got a nice looking GUI (that does all the stuff GUIs do - see the demo) ...

Maybe they'll deliver the goods. Maybe Microsoft have something up their sleeves. Who knows? Not me!

MadCap's demo page is at:
www.madcapsoftware.com/products/demos.asp

Maybe by the time you read this they'll have added a more interesting demo.

One result of this is that the link I was using to get to the helpauthoring newsgroup (which I included in my posting of 19 May) no longer works.

The alternative is:

www.microsoft.com/communities/newsgroups/en-us/default.aspx?dg=microsoft.public.helpauthoring

If you're using Internet Explorer, this is a good alternative to the previous version. If you're using Firefox it looks horrible and isn't easy to use.

How like Microsoft to develop an IE-only solution.

If, like me, you use Firefox as your default browser, a handy tip for IE-specific websites like this is to put an IE shortcut on your desktop (or somewhere else that's easy to find).

If you just drag a shortcut from the address bar, the shortcut will open your default browser - even if you drag the shortcut from IE. So you have to specify the browser you want to use in the shortcut.

For example, right-click the desktop and choose New > Shortcut. In the Create Shortcut dialog box, click Browse and browse to the location of the Internet Exporer application, iexplore.exe, (typically the path is C:\Program Files\Internet Explorer\iexplore.exe).

Now copy the path to the newsgroup:

"http://www.microsoft.com/communities/newsgroups/en-us/default.aspx?dg=microsoft.public.helpauthoring"

including the quote marks, and paste this in at the end of the location text box.

The location the shortcut is pointing to should now look like this:

"C:\Program Files\Internet Explorer\iexplore.exe" "http://www.microsoft.com/communities/newsgroups/en-us/default.aspx?dg=microsoft.public.helpauthoring"

Click Next, give the shortcut a suitable name (e.g. helpauthoring) and click Finish.

You can now double-click this shortcut and be taken straight to the newsgroup, in IE, even if your default browser is something else.

If you want to you can change the icon of your shortcut by right-clicking the shortcut, choosing Properties, clicking Change Icon and selecting an alternative icon, or browsing to an application or a DLL that contains an icon you want to use instead (e.g. %SystemRoot%\system32\SHELL32.dll contains a good selection - I chose the Windows butterfly).

The trouble with this newsgroup is that you have to know about it.
It's not that easy to find. So here are some ways to get to it.

Using your browser

This is the way I usually read this newsgroup. Browse to:

http://communities.microsoft.com/newsgroups/default.asp?icp=web_publishing_all&slcid=us&newsgroup=microsoft.public.helpauthoring

This provides a nice interface to the newsgroup. The drawbacks with
this method are that you have to type in your name/email every time
you post a comment and you don't see any attachments that people
might post.

[Update: The above link no longer works. Microsoft changed the interface to this newsgroup shortly after I posted this. See posting of 19 May.]

Using a newsreader

My newsreader of choice is Thunderbird. To read microsoft.public.helpauthoring
in Thunderbird, set up a new account for the public news server msnews.microsoft.com.
Once the account is added, click Manage newsgroup subscriptions.
Search for helpauthoring and subscribe to microsoft.public.helpauthoring.

The drawback with this approach is that you don't get any message
threading, you just get a separate entry for each posting –
so it's difficult to read through a set of connected postings. Thunderbird
normally handles threading very nicely. I can only assume it's something
to do with the way msnews.microsoft.com serves up
it's newsgroup output.

However, not all newsreaders suffer from this problem ...

Using Outlook Express

I don't like to suggest you use Outlook Express, but it does
handle message threading for microsoft.public.helpauthoring.

Set it up in more or less the same way described above. Or –
if Outlook Express is your default newsreader – clicking the
following link will set it up for you:

news://msnews.microsoft.com/microsoft.public.helpauthoring

It's quite handy to drag this link to your Bookmarks/Favorites as
a quick way to get to the newsgroup.

Using RSS

You can use the following link to Google Groups to add an RSS feed
to your newsreader (e.g. Thunderbird) or to the Sage add-on for Firefox:

http://groups-beta.google.com/group/microsoft.public.helpauthoring/feed/msgs.xml

However, this also does not provide you with any threading.

Google Groups provides an alternative way to read postings in a
browser. Browse to:

http://groups-beta.google.com/group/microsoft.public.helpauthoring

However, I don't like the way this is set out and I don't find it
easy to use. Also, some replies seem to be missing. On the plus side,
using Google Groups to search the newsgroup does provide a very quick
way of finding information in old postings.

Put the following batch file in your help directory. In my case this directory contains various subdirectories, one for each help project. The one I'm currently working on is called imuser, so this is the default project directory in the batch file, and the help file within this subdirectory is imuser.chm, so again this is the default. Change the two lines near the top of the batch file to change these defaults.

Once in place, all you do is double click the batch file in Windows Explorer, or double-click a shortcut to this batch file on your desktop, or in your Favorites, and a console window opens prompting you for the path, file name and map ID you want to use. You can hit Enter twice if you want to accept the defaults, but you must enter a map ID.

The help file is opened using keyHH.exe, which is a free download from Keyworks Software.

The batch file:

@echo off
REM =================================================================
REM   test-help.bat
REM   -------------
REM   A Windows batch file for testing context-sensitive help.
REM   Copyright Alistair Christie, 18 May 2005
REM =================================================================

REM   Set the relative path to the directory containing the help file,
REM   and the name of the help file.
REM   Note the path is relative to the location of this batch file.
set helpdir=imuser
set helpfile=imuser.chm

REM   Set %basedir% to the directory in which this batch file lives.
set basedir=%cd%

REM   Print a blank line
echo+
echo CONTEXT-SENSITIVE HELP TESTER
echo =============================
echo Requires you to have downloaded and installed keyHH.exe
echo from http://www.keyworks.net/

echo+
echo The help file your are about to test is:
echo %helpdir%\%helpfile%
echo+
echo within the current directory:
echo %basedir%

:start
echo+
echo Path: %helpdir%
echo If this is not correct, enter the correct path
echo (without the trailing \), relative to the current directory.
REM   Get user input and put it in the variable %newhelpdir%
set /p newhelpdir="If this *is* correct, just press Enter: "

if not {%newhelpdir%}=={} set helpdir=%newhelpdir%\

echo+
echo File: %helpfile%
echo Press Enter if this is correct.
REM   Get user input and put it in the variable %newhelpfile%
set /p newhelpfile="Otherwise enter the correct file name: "

if not {%newhelpfile%}=={} set helpfile=%newhelpfile%

:enterMapID
echo+
REM   If this is not the first time round, the user will already have supplied a map ID
if not {%mapid%}=={} echo Map ID: %mapid%.&set /p mapid="Press Enter or enter a new map ID: "
REM   If this *is* the first time round, the user must supply a map ID
if {%mapid%}=={} set /p mapid="Enter a map ID: "
REM   If they don't, print an error message and exit
if {%mapid%}=={} goto :noMapID

REM   Change to the specified subdirectory
REM   within the base directory (i.e. the directory
REM   in which this batch file lives)
cd %basedir%\%helpdir%

REM   Use keyHH.exe to open a help topic
REM   using its map ID

echo on
keyHH.exe -myHelp -#mapid %mapid% "%helpfile%>$global_ContextWindow"
@echo off

echo+
echo Enter:
echo 'a' to choose another help file to test,
echo 'x' to exit
echo Or just press Enter to test another map ID.
echo+
REM   Undefine %keypress%, just in case it's been used previously
set keypress=
REM   Get user input
set /p keypress=""

REM   If 'a' entered, clear the screen and go to the 'start' marker
if {%keypress%}=={a} cls.&goto :start
REM   If 'x' entered, quit this program (closes the console window)
if {%keypress%}=={x} exit
REM   If anything else entered (apart from a space),
REM   clear the screen and go to the 'enterMapID' marker
cls.&goto :enterMapID

:noMapID
echo+
echo+
echo+
echo ERROR: You didn't enter a map ID
echo The program will now exit.
echo+
REM   'pause' prints a predefined message and waits for any keypress
pause

Pretty much all of this batch file is user interface window dressing. The guts of the file lie in the line:

keyHH.exe -myHelp -#mapid %mapid% "%helpfile%>$global_ContextWindow"

For this to work, you obviously need keyHH.exe, but you also need a help file that has a window definition called "$global_ContextWindow" and that has map IDs set up.

You could, however, remove ">$global_ContextWindow" from this line if you just want to use the default window for the help file.

When you run it, the batch file looks like this:

You need to specify two Item parameters for the Shortcut command.

it is probably because you are using a networked help file.

I have a topic containing the following link, which is meant to open a PDF in a separate browser window:

<object
    classid="clsid:ADB880A6-D8FF-11CF-9377-00AA003B7A11"
    id="OBJECT1" type="application/x-oleobject">
    <param name="Command" value="Shortcut">
    <param name="Text" value="Text:User’s Guide">
    <param name="Font" value="Verdana,8,0,,UNDERLINE">
    <param name="Item1" value=",userguide.pdf,">
</object>

This works fine if everything is on the local machine, but if I try to use it on a network server, it fails with the above message. The reason for this is a security fix in version 1.4 of the HTML Help viewer that prevents the viewer being used to open up files on a remote computer. This was a big security hole in previous versions of the viewer.

For more details, see:
http://helpware.net/htmlhelp/hh_info.htm#hh14

At the time of writing there's an interesting discussion about this on the Macromedia General Discussion forum:
www.macromedia.com/cfusion/webforums/forum/messageview.cfm?catid=447&threadid=979594&forumid=65

At first it seems odd that Macromedia should spend $65M on aquiring eHelp and then decide not to continue development on eHelp's flagship product. However, probably shouldn't be too surprising. The future of technical documentation is XML-based and many technical authors are looking for tools that will support the creation and maintenance of MAML-based documents. Whatever the eventual successor to FrameMaker and RoboHelp turns out to be (perhaps something from Madcap, perhaps something from ArborText, perhaps something Macromedia have up their sleeves) it will need to be built around MAML, and almost certainly (though perhaps as a by-product rather than a main aim) make DocBook authoring much simpler than it is right now.

www.robowizard.com/RoboWizard/NewProject.htm#Downloads/Tips_and_Tricks.htm

There's a lot of good stuff in there, including the fact that you can dig around in the behind the scenes data of a RoboHelp project by opening the .mpj file in Access. I hadn't realised that this file is a database containing a set of tables - one for each of the different parts of a help project (Windows, Merge Files, etc.).

I found another useful tip on Rick Stone's website. It's a fairly obvious idea - but then those are sometimes the best ones. Imagine you want to include in your help system a link to a large user manual in PDF form. When the user clicks the link you want the PDF to open up in a new browser window. Nothing difficult here, but the problem is that on slow machines this can take a while. The user clicks the link and thinks it's broken because nothing happens straight away.

To prevent this confusion you need to display an intermediate page saying something like "Please wait. The User Guide will be displayed shortly." To do this, make the link go to a page containing this message, and in the head of this intermediate page but the following meta tag:

<meta http-equiv=refresh content="1;URL=LargeUserGuide.pdf">

This tells the browser to start loading the PDF after one second (you'll probably want to change this to 0). All being well the message will remain on the screen while the PDF loads. When it loads it will do so in the same browser window. The effect is that the user gets some immediate feedback.

You can do the same thing by pointing all such links to a single redirection page containing JavaScript that works out which page to redirect you to. The good thing about this is that you only need to maintain one redirection page. The JavaScript section contains details of all the destinations, and you tell the JavaScript where to redirect to by including a code word in the URL of the page, in the form of an anchor reference. For example, if the redirection page is called redirection.file, you might call it with the URL redirection.file#UserGuidePDF. The script has another URL mapped to the code UserGuidePDF. Here's an example of the redirection page:

View whole page

1:  <html>
2:  <head>
3:
4:  <title>Redirection page</title>
5:
6:  <!-- This file is used to get display a "please wait..." message
7:           while the browser loads another file.  -->
8:
9:  <script language ="Javascript">
10: <!--
11: var Code = window.location.hash.substring(1);
12: var URL= "" ;
13:
14: if (Code == "UserGuidePDF") URL="PDFs/UserGuide.pdf" ;
15: else if (Code == "AdminGuidePDF") URL="PDFs/UserGuide.pdf" ;
16: else if (Code == "WordDoc") URL="Don't%20use%20spaces%20in%20file%20names.doc" ;
17: else if (Code == "SpreadSheet") URL="spreadsheet.xls" ;
18:
19: if (Code == "")
20: window.location.replace("homepage.html");
21:
22: if (URL != "")
23: window.location.replace(URL);
24: else if (Code != "")
25: alert("Error in redirect.file\n\n" +
26: "No URL has been specified for the anchor: \"" + Code + "\"");
27: //-->
28: </script>
29:
30: </head>
31:
32: <body>         33: <p>Please wait. The page you requested will be displayed shortly.</p>
34: </body>
35:
36: </html>

One of three things happens when you load this page:

1) If you call it with one of the anchors it knows about (e.g. redirect.file#UserGuidePDF), it displays the "please wait" message.
2) If you call it with an anchor it doesn't recognise, it displays an alert box, with an appropriate error message.
3) If you call it with no anchor, it redirects you to a default page.

Thanks to Rob Chandler (The Helpware Group website: http://helpware.net/htmlhelp/how_to_merge_ctx2.htm) for details of how to do this type of redirection.

Notes:
1) This is intended for HTML Help, so it only works in IE. However, with a bit of tweaking you could get it to work in other browsers.

2) I've called this file redirection.file rather than redirection.html so that it doesn't get parsed for a full-text search in the help file. I don't want it showing up in the HTML Help Viewer's search results if the user searches for "wait".
3) Thanks to Jean-Claude Manoli for his wonderful online code formatter (www.manoli.net/csharpformat), which I used to produce the nicely coloured/formatted HTML code you see above.

-----
*You can get to the microsoft.public.helpauthoring newsgroup at:
http://communities.microsoft.com/newsgroups/default.asp?icp=web_publishing_all&slcid=us&newsgroup=microsoft.public.helpauthoring

-----

"MJ's Diagnostics is a small utility that reports if all the HTML Help runtime DLLs are installed and registered correctly. If a DLL is not registered then it will ask if you want to register it. It also checks the RoboHelp DLL (HHActiveX.dll)."

Download it from:

http://helpware.net/downloads/

Note: I've downloaded and run this on my computer with no appreciable side effects (so far), but I can provide no guarantee that the download site linked to above is bona fide, or that it is completely harmless – I just crossed my fingers and trusted to Norton Antivirus.

But sometimes you want to see the resulting HTML, after the .js file has done its work. You can't use View Source because all you get is the static HTML. One way to display the dynamic HTML is to:

1. Open the .chm file and display the page you're interested in.
2. Right click a topic in the Contents pane.
3. Choose Jump to URL.
4. In the Jump to this URL field, paste this:

javascript:void(window.open("javascript:document.open('text/plain');document.write(opener.document.body.parentNode.outerHTML)"))

When you press OK, the HTML is displayed in a new IE window. The HTML that is displayed is the HTML that the browser window in the Help Viewer uses when displaying the topic.

UPDATE - Jan 2009

The above doesn't work in Internet Explorer 7. However, this does work:

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

As above, paste this into the Jump to URL dialog box.

The help system was modelled after the help for Internet Explorer 6. Like that
system, mine had a “Related Topics” link at the foot of most topics.
The problem was that unless I had an old version of the hhctrl.ocx
Active X control installed I couldn't get the list of related topics to be displayed
in a popup (IE-style) rather than a dialog box. I scoured the Internet for a
solution, to no avail. As a workround I got our development department to add
the old hhctrl.ocx to the client software installation, so
that it gets registered when you install our software. The trouble with this
is that as soon as the user installs a new Windows service pack, or installs
another program that registers a newer version of this Active X control, the
popups go back to being displayed as ugly dialog boxes.

Now it's time to update the help system for a new release of the application.
I was determined, this time round, to get those Related Topics popups working.
But I still couldn't find anything on the Internet, apart from one
mention, with the following explanation:

“This will happen if the language of the OS doesn't exactly match
the language of the chm. The problem is that in some cases this mismatch causes
garbage in the menu (if the language of the chm can't be displayed in the font
the system uses for menus), so we fall back to the Topics Found dialog, in which
we can set the font.”

Gee thanks! So that clears that up then. NOT!

As a last resort, I thought I'd give newsgroups a try. The obvious newsgroup
seemed to be microsoft.public.helpauthoring. I added this newsgroup to Thunderbird
and searched through the postings for anything on “Related Topics”.
No joy. No joy, too, when I tried to post a query. Thunderbird complained about
there being “no sender”, despite my name being in the Sender header.
Okay, never daunted, how about using Microsoft's web front end to their newsgroups
as an alternative way of posting to microsoft.public.helpauthoring. Not as easy
as you might think.

Microsoft's online newsgroups are incredibly difficult to get to if you don't
have a URL or a link to a particular posting within a particular newsgroup.
You'd think you'd be able to go to the main Microsoft page, click the Communities
link, then click the Newsgroups link, then search for the “helpauthoring”
newsgroup. Wrong! If you click the Newsgroups link you get to a page called
“Welcome to Microsoft Discussion Groups” where you can search for
topics across all newsgroups and you can view the posts you find, but you can't
get to a particular newsgroup and you can't post a question/reply.

One way to get to the newsgroups – though I can't recommend it –
is to go to http://communities.microsoft.com/newsgroups/default.asp.

When you browse to this page, a list of public newsgroups starts loading in
a pane on the left of the window. But wait a minute (wait a lot of minutes,
if you have a dial-up connection), because if you try scrolling down the list
too far, too soon, it may stop loading, and then you have to refresh the page,
and start waiting again. Sometimes it just stops loading even if you don't do
anything and it gives you some incomprehensible message about “no data”.
This is a seriously badly designed web page!

By the way, why are Microsoft's web sites SOOOOOOO SSSSSSLLLLLLLLOOOOOOOOOWWWWWWWWWWWWWWW.....?
I can only presume Microsoft have shares in cable companies.

As I said, the only decent way of getting to one of the web-based versions
of Microsoft's newsgroups is to use a URL. Here's the URL for the “helpauthoring”
newsgroup:

http://communities.microsoft.com/newsgroups/default.asp?icp=web_publishing_all&slcid=us&newsgroup=microsoft.public.helpauthoring

If you go to this page and you like accessing the newsgroup that way, be sure
to bookmark the page, or you may have trouble finding it again.

So I posted off my question and, wouldn't you know it, when I check back a
couple of hours later, there's a reply. Not just a reply though: the solution
I had been searching for. The correspondence was as follows:

That totally reinforced my firm belief in the immensely beneficial power for
sharing information offered by the Internet. Next time maybe I won't be so slow
to turn to a newsgroup for help.

Incidentally, Pete Lees, who replied to my query, runs an excellent Help Wiki
at: www.mshelpwiki.com, which I can
recommend.

Another useful resource I came across while looking for an answer to the popup
problem was: www.chmtools.com. This provides
useful information about help authoring tools, and links for downloading those
tools, including htm2chm by Yaroslav Kirillov, which reputedly
“Allows you to convert separate HTML pages with images as well as
whole websites (for example downloaded with offline browsers) into one CHM file
for more convenient storing.” I haven't tried this yet, but it sounds
intriguing.

One program I did try, and I can thoroughly recommend, is KeyTools
by KeyWorks Software. Among other things it allows you to decompile a .chm
file into its component parts. Okay, I know, HTML Help Workshop can do this
very nicely. But KeyTools does it even better. It's very useful for answering
“How did they do that?” type questions.

You can find a list of help authoring newsgroups and forums at: www.chmtools.com/forum.
However, you need to register to post to these newsgroups via this web site.

I'm very happy now that my Related Topics are finally displaying like I always
wanted them to. One final question remains through all this though. If someone
at Microsoft broke hhctrl.ocx some time ago, how come they've
never bothered to fix it? The answer, surely, is that this bug only affects
technical authors outside the US. There just aren't enough technical authors
close enough to Redmond, waylaying them in the street and accosting them at
conferences, to make it worth their while getting round to fixing this bug.
Of course, things have moved on now, HTML Help is out and MAML is in –
so this bug will never get fixed now. But who cares? I've got the workaround
I was looking for. That'll do me!

Here's a useful page full of links to information about MAML (Microsoft Assistance Markup Language):

http://longhorn.msdn.microsoft.com/lhsdk/port_tech_helplh.aspx

MAML is Microsoft's XML dialect for producing .HELP files for the next version of Windows (currently named "Longhorn" and recently shunted backwards for release some time in 2007). MAML is a hugely sensible move on Microsoft's part. Anyone who is familiar with using an XML dialect for documentation – for example, DocBook – will find MAML very easy to get to grips with.

Microsoft could have adopted DocBook, but when you're Microsoft you don't adapt existing technologies that don't quite fit what you want to achieve. It was cleaner and probably easier to start from scratch and devise a new, purpose-built XML variety for "assistance" documentation (in most cases that means online help).

If you write online help you'll be hearing a lot more about MAML in the coming months.