This is something I’ve blogged about twice before (in March 2004 and in January 2009), but going back to those topics just now neither of the solutions I gave at that time are working for me. So here’s the way to do it now.

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

A recurring problem with generating Microsoft HTML Help output is that, if you don’t have the correct DLLs registered, then you can encounter issues. A common issue is not getting any search results. You open the CHM file, click the Search tab, enter a word that you know is in the help file, but all you get back is:

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.

I've written before (see Does online help need an overall structure? and What online help needs is really good search results) that I think the best way to present online help is with a simple page with a big search box at the top, above a selection of links likely to be useful to users needing help. Do away with the book metaphor used in many help systems: the table of contents and the index. Just make sure the search gives really spot-on results.

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. 

The way I learned to write documentation was that you started work on a new project by spending a decent amount of time getting to know your subject matter. I don't mean getting to know the software, I mean getting an understanding of the environment in which the software will be used and the reason for its existence - that is: what's the real value of the software to its users and what do they want to achieve by using it? This is a period of talking to the product managers and subject matter experts and reading up on everything you can find that sheds light on the world in which the product will live.

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 Johnson recently wrote a really though-provoking post about the scope of help content. What you’re reading here is based on a comment I added to Tom’s post.

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.