Is there a way to apply annotations to .chm output?

[joanneteasdale]

Several of our end users have requested the ability to apply annotations or notes to our .chm Help files. They had this capability in WinHelp and now that we're shipping HTMLHelp they miss this functionality. I've seen some .chm files that offer an "Annotations" button, so I know it can be done, but I'm not sure how to go about creating this (I know it's not a Flare feature). Can anyone provide some guidance?

[Stefaans]

In the Skin editor, there are options to enable topic comments and recent comments. Enabling these features have no effect on the compile HtmlHelp output though. I have had a look at the documentation of HTML Help Workshop (Microsoft's archaic help builder) and found no reference to allowing user comments. All of this suggests to me that it is not possible

[Andrew]

Hoo boy, this can be a bit of a doozy. I've been messing with this for a while, and I've never figured a really workable solution. The basic problem is that, to get any robust functionality, you have to do things in CHM which are considered a "no-no" in terms of security (like accessing a data source, or a file system). Microsoft security fixes have either broken methods, or have rendered them unusable due to the security prompt that occurs every time you open a help topic (unless you set the user's browser to be extremely insecure, which is a Very Bad Thing you should NEVER ask users to do).

If all you want is the ability to click a button and be able to get an editable text file, that's easy. You can insert a help control into an HTML Help project that will open notepad with a certain file name (which you pass as a parameter). Very simple and basic. The drawback to this method is twofold:
1) You have to specify the parameter (the individual file names you want to use) for every single topic that includes the help control. I used topic names as the file names. When the user clicks the help control link, the txt file with the name of the topic opens. If no such file exists, Notepad asks the user if they would like to create the file.
2) In the WinHelp Annotate feature, a little clip graphic appeared if the user had made any annotations to the topic. The help control method does not allow you to have any such icon (without accessing the file system, which generates all kinds of security warnings from your browser). So your users will have to click the help control link every time they want to see if an annotation exists.

There are other methods as well. For example, Dave Gash lists one on the Winwriters web site (beware, it's pretty old, but I think all the code still works). It uses cookies as a method for creating annotations. This is great for individual user annotations (which is what WinHelp used to provide for the most part, anyway). This might work for you -- it can't work for me, since my users want annotations that live on the network, and are accessible to all the application's users (I write for a multi-user database-driven app where there is usually just one copy of the help file for an entire company).

There are other solutions, but most of them are pretty overkill (such as switching to WebHelp and either hosting the help yourself, or requiring users to host it, and developing a set of functionality that will create the annotations via the WebHelp, or developing your own client application "frame" for your help and building the annotations capability into the frame).

One last note: you could also try something like CHM Editor. I haven't used it, but if your users are wiling to pay for a license, they can edit the help files directly (obviously, for shrinkwrap, off-the-shelf type software, that won't be a very compelling product, but for more business-oriented software, it might work). I haven't used it myself, so I don't know how effective it really is.

[Andrew]

In the Skin editor, there are options to enable topic comments and recent comments. Enabling these features have no effect on the compile HtmlHelp output though. I have had a look at the documentation of HTML Help Workshop (Microsoft's archaic help builder) and found no reference to allowing user comments. All of this suggests to me that it is not possible

Topic Comments are only available if you purchase MadCap's Feedback Server or Feedback Service. They basically enable you to display user comments on topics, which is, IMO, not at all the same as annotations. User comments works more like a blog comments, where you as the author have very few options as to who can see whose comments. If your customers were willing to pay for the service/server themselves, and you were willing to create a separate build of your CHM for each customer who wanted this, you could offer each customer their own personal comments area, so that it would be more effective as an annotation device, but that's an expensive and complicated proposition.

[Stefaans]

Thanks Andrew, those were two great posts

[joanneteasdale]

Thanks so much for the informative replies--all very helpful!

[doc_guy]

joanneteasdale,

Welcome to the forums! Let us know if we can help with anything else!