Working with Programmers to Create Context-Sensitive Help

My main job, which I consider “real” technical writing, is creating the help that is installed with an application. Context-sensitive help (CSH) provides a better user experience than always opening an intro topic. That is, a user is trying to modify a site and isn’t sure what to type in a particular field, so he clicks Help. A help topic appears that describes exactly how to modify a site. That’s CSH; the topic appears based on the context in which the user clicked Help.

The developer/programmer can add “help hooks” and “help IDs” (code) into the code for the Help button. (He also has to add code to call the help—tell it which file to use for the help, what to display, blah, blah, blah, but I’m not a programmer.) So if the developer is creating a dialog box named New Site and adding a Help button, he might add a help hook named HIDD_NEW_SITE with an ID of 0x204FF*. When the developer is done coding, ready for QA to test the application, or the technical writer nags him that she needs the help hooks, he can export a file from his coding application with a .H, .HH, or .HM extension**. And with that, the developer’s contribution to the Help is complete–unless he made mistakes or forgot to add some help hooks. (Alternatively, the technical writer can define help hooks for each topic, create the .H, .HH, or .HM file, and send it to the developer to add to the code.)

When I’m writing new help topics or editing existing help topics, I install the latest build (in development) of the application on a virtual machine (VM) so I can write more intelligently about what it actually does when I click, right-click, and so on. In some ways, I’m doing “QA” on it and writing up bugs that I find, but I don’t do a formal QA. (We have smarter people than I to do that.) One of the things I do test for, however, is whether the help appears at all and, if so, if the topic is relevant (context-sensitive). I can tweak the CSH files to link a specific help hook to a different topic, if needed.

Often the name used for the help hook is not very intuitive (HIDD_AFTER_INSTALL7) , so I need to ask the developer which ID is assigned to which dialog box. First, I create a spreadsheet that lists the dialog box, the help hook, and the topic that I think should appear for that dialog box. (Remember, that the developer may not have ever seen the interface, just code and COM API interactions.) I then email the spreadsheet to the developer and ask him to fill in the blanks. Seems simple, right?

Sometimes a developer has no clue what I’m talking about, either because he’s never worked with CSH before, he didn’t read the email, or English is not his first language, and so he responds that the error is on my end. If this happens to you, use your “detail oriented” technical writing skills to verify that the following is true:

  • You have the correct help hooks file (.H, .HH, or .HM). On one project, we had 5 different HM files and I had no idea which one I was supposed to use, and neither did anyone else. (The most recent one? Not necessarily.) The fix for that is ask them to export a new one. If you already reference it in the help authoring tool, ask if they can name it the same, to make your life easier.
  • Each hook in the .H, .HH, or .HM file has “#define” and a space in front of it. Sometimes they don’t.
  • Your map file or alias file (the .ALI file) is formatted correctly and ALL of the correct hooks linked to relevant topics. (You don’t have to link every ID in the .H, .HH, or .HM file, just the ones that are assigned to Help buttons.)
  • The ALI and .H, .HH, or .HM file are properly referenced in the HHP file.

If you don’t edit the ALI file directly, but prefer to do it in RoboHelp, make sure RoboHelp still “sees” the hooks. When I copy and paste an updated version of the file into the project (overwriting the existing, same-named file), RoboHelp sometimes forgets it. I don’t know why. Of course, if this a new file, you have to import it–RoboHelp doesn’t know the file exists if you just paste it into the project. You must import it to add it to the project files.

After you’ve fixed your mistakes (or you’re positive you haven’t made any mistakes), generate the CHM again and paste into your VM with the latest build installed. (When you generate the help, you can view the log file to see if there are any errors that you can fix.) Test every Help button, using your spreadsheet as a reminder of which dialog boxes have Help buttons. You should test every button every time, because sometimes you break things unintentionally when you’re fixing other things! If you’ve decided everything is working on your end, ask/email the developer again, ask him to review your worksheet, and point out the exact help hook(s) that you believe are broken. (Developers are busy people and usually get paid a lot more than you do, so make it easy for him to scan the email to see what you’re asking him to do.)

Microsoft HTML Help Workshop (HHW.exe) is a utility to test that you have valid files. It’s an old app that Microsoft no longer updates, but it still does the job. In HHW, specify the CHM you want to test, then click Tools > HTMLHelp API. In the dialog box that appears, select HH_HELP_CONTEXT and then type in a map ID (decimal or hex works).  When you click OK, the topic that you want to appear for that map ID should appear. If the wrong one opens or nothing opens, you need to fix the .ALI file. If a message appears that says something like “HH_HELP_CONTEXT called without a [MAP] section” that means something is broken. (Duh.) You can decompile the CHM (in HTML Help Workshop) and see that there is, indeed, a [MAP] section, yet it doesn’t “see” it. Why not??

If you get that message, ensure that the .ALI and .H, .HH, or .HM are properly referenced in the .HHP file. Computers aren’t very smart—you make one mistake and they get confused! (One time I had to generate WebHelp, before the HHP file would update. I wasn’t about to manually add a bunch of files! I do merged helpsets, so I need a valid HHP for that.)

This is important to understand: if your CHM works in HTML Help Workshop, that does NOT mean that it works in the application! All it means is that the .ALI file and CHM are properly formatted and a topic opens when you provide the hook. Period. For example, you could have two of the help hooks reversed or wrong topics referenced, but the CHM will still “work” in HHW. The only way to be sure your CHM works in the application is to paste it into the installation folder (or wherever the existing CHM is stored), and then try it in the application. Your application will have to be closed to do this; otherwise, you’re trying to overwrite a file that is in use.  In my last experience with “broken” CSH, the developer had forgotten to add hooks to the dialog boxes that didn’t open the correct help. He kept insisting that the CHM worked for him. After three emails asking him to please test it in the application, not in HHW, he finally accepted that it was broken in his code.

Usually the application is coded such that if a user clicks a Help button and there is no help ID assigned to it, the default help topic (e.g., Intro) will appear. So when that happens in my testing, that’s a pretty good clue that either there is no help hook or I didn’t add it to the ALI file. Don’t let the developer intimidate you. You might be doing something wrong, but if all he tells you is that the problem isn’t in his code (rather then telling you specifically what is wrong with yours), ask for more information. He should be able to tell you, “When I click the Help button on the New Site dialog box, this ID is triggered, but the CHM is opening the Intro topic.” You can then verify that the ID is in your ALI file and linked to the topic that you want to open. (If he had looked at your spreadsheet, he would have seen which IDs you were using for each Help button.) Of course, if release is happening soon, opening the Intro topic is better than having no help at all!

*Help hooks in the app are in hexadecimal (0x204FF). Help authoring apps like RoboHelp list them in decimal. If you want to convert the hex number to decimal, open Windows Calculator (click Start, then type calc.exe), click View >Programmer, type the hex number, then click Decimal. The number is converted to decimal.

**In this article, I’m talking about Microsoft HTML Help (CHM). The basic process is similar, but in JavaHelp (JH), the map file is simply called a “map file”–imagine that!–and it’s formatted slightly differently. This is how I learned how to write JH: http://shop.oreilly.com/product/9781565927193.do. I highly recommend buying the book (because knowing how JH works will help you fix it when it doesn’t work!), but this page  gives you the general idea if you just need a refresher: http://oreilly.com/catalog/creatingjavahelp/chapter/ch05.html

Advertisements

“This product is awful” usually means you can’t figure out how to use it

Documentation not only needs to educate your customers and provide on-the-spot troubleshooting assistance, but also can be used as a sales tool and a revenue generator. I’ve never been a fan of putting marketing-speak in technical documentation—that’s not what I mean by “sales tool.” What I’m saying is that providing good documentation allows prospective customers to more accurately ascertain whether your product meets their needs. With up-to-date online documentation, a prospective customer can quickly find the information he needs on his own. If your documentation doesn’t provide enough information, potential customers will find a vendor who does. A thoroughly documented product also gives the impression that the product is easier to use than your competitor’s, whose product documentation was written one Sunday morning by a developer needing to meet a release date. Good documentation before the sale gives the customer faith that the documentation after the sale will be as good. Companies that are consistently the winners in their industry care about educating their customers and prospective customers. Failure to properly document your product creates an opening for your competitor to capture that customer.

When someone says “this product is awful,” what they usually mean is that they can’t figure out how to use it. If they attempt to use poorly written documentation to figure it out, they are even more convinced that the product is bad. Good documentation results in happier, loyal customers and reduced customer support costs; customer support can spend more time providing higher value service and less time “hand holding” capable customers. Sure, good documentation can be expensive; but according to Forrester, the average call center call can cost a business as much as $50 per call. For technical issues, costs per support call can be as much as $150 per call. If customers can use the documentation or an online forum to solve their problems, the average cost is usually less than a dollar. In fact, Forrester’s research indicates that the average is about 10 cents per customer.

Most companies gather statistics on how many support calls are generated in a day. Based on the high volume of calls, they assume that the documentation is not being used. They fail to note how much customer support uses the documentation to help the customer. A large percentage of customers would rather call support, ask a specific question, and be told exactly what to do to fix their problem. This type of customer will never use the documentation unless they have to pay for phone support. Online help that allows the customer to provide feedback can provide statistics regarding not only how many people actually read that particular help topic, but also can tell you whether customers think the information is useful or a waste of their time. (Microsoft Support is a good example of this.) Product managers can use that feedback to improve the product and the documentation.

Some help documentation tools and formats allow for user feedback forms (“Web 2.0”), but having the ability to type comments into a form on a help topic is not enough. You also need a connection to a server that can store the feedback. With the right software, you can also view and print reports of which topics are used most often and what the comments are, which can tell product managers which areas of their application might need improvement to make it easier for users to understand.

Even though the products that I document use in-application help, I also provide online, web-based help. In that help, I could easily create a web form in which anyone who visits the topic could rate the topic and add comments that could improve the topic. Their comments would be visible to other users of the topic and, most importantly, to me. I could use their comments to improve the topic and the product manager could use their comments to improve the product. However, I don’t have the application that I need to manage the comments, store the comments, or report on the comments. Many companies won’t allow you to use a product that has a user feedback system or want to spend time creating their own automated user feedback system. So the best you can hope for is a user forum or a knowledgebase tool that allows user feedback, but that’s a manual system, doesn’t provide for reporting, and doesn’t tell you whether your help documentation is helpful or confusing.

One day, “Web 2.0” help with be the norm. For now, just keep plugging away at your help and hope that the feedback you do receive helps you improve your documentation.