How long does it take to write the user documentation for a small program such as my accompaniment generation program? A good deal of time, actually. That’s almost all I’ve been working on in the past few days. I also made the problem a little more interesting by requiring that a single source for the documentation be used as a help book for Apple Help as well as be readable online at my web site.
Apple Help defines a number of extensions to HTML to support additional browsing features in the Apple Help Viewer. They’re Apple’s own standard so web browsers generally don’t support them. So the question is whether these can be avoided while the documentation source can still satisfy the requirements for a help book. The answer is “yes” if we’re willing to avoid the use of the “help:” protocol and lose the ability to provide hyperlinks that run AppleScripts, initiate searches in the help viewer, and so on. For a simple help book such as mine, this is OK.
Since web browsers ignore unrecognized meta tags, the use of these in help pages to specify keywords and descriptions are fine. The Apple Help Indexing Tool in fact uses them to generate an index file for the help book, so typing keywords into the search box identifies relevant help pages. A note about that tool though: it appears if file names for the help pages are too long (about 32 characters, does that sound familiar?), it generates an index in which some links fail when clicked! The tool looks every bit like it’s from the classic era. Oh well...