Help Writing Help for your Application
Make a Rough Plan First
Before getting into the nitty gritty of Help Files, Topics and Help Context ID's it's well worth sketching out a plan for your application containing a list of which forms will have help and roughly to what depth that help should go.
Generally you should aim to create unique help topics only for those forms and controls that need it, don't create help topics just because you can. The primary reasons for this are firstly to keep the cost of producing the help down and secondly to keep managing and maintaining the help within reasonable bounds of time and cost. It is quite tempting to produce complex all encompassing help when you start out. Don't give in to that temptation. You'll just create something you probably won't maintain and put yourself off doing any more. Users will also be put off if confronted by something that looks complex and difficult.
This is a fine line to walk. Whilst you must try to put in enough information to be beneficial, don't try to cover every eventuality in your help system.
You should certainly consider creating one or more 'How To' topics which might not be linked to any Access Help Context ID (form or control) but will appear in the Help Contents or Index. These can be of great help to new users and will tend to give your application a positive feel.
Tip of The Day screens that optionally display when your application is started can be a good idea but will not form part of the Help file system. They should be a separate form/table subsystem within your application.
You should also decide whether to create an HTMLHelp project, a WinHelp project or both. For context sensitive help fired from the F1 key in Access these are the most obvious options.
WinHelp Or HTMLHelp?
You can agonise over this for ages. There are pro's and con's for both and a third kind of help system may yet be introduced by Microsoft (search for MSHelp2 and Longhorn Help on the HelpWiki). There are also some third party help systems just to complicate matters.
The HelpWiki site is an invaluable resource for Help authoring and making. I recommend bookmarking it and the MVPS Help site by Dave Liske. Dave's site has some excellent articles especially regarding use of HTMLHelp with Access 97 and Access 2000.
See also Tony Toews site section on adding Help to Access applications.
WinHelp is the 'old fashioned' help system and will work on 99% of current PC's. HTMLHelp is the current official help system and will in theory work on any PC with Internet Explorer v4 or later installed. You can do more with HTMLHelp than WinHelp.
WinHelp projects load faster, are more reliable on different machines and don't require IE. HTMLHelp is the de-facto standard at the time of writing (spring 2004).
I now make Help in HTMLHelp. Since most Help Authoring tools will do both kinds of help these days it's fairly easy to produce and maintain both types and give people the option. My own preference is HTMLHelp.
Skeleton files for both types can be created using my automatic Access Help File Maker - AccHelp.
WinHelp File Production
I strongly recommend using a Help authoring tool and of course I would like you to buy a license for my application AccHelp aswell.
My favourite help authoring tool is HelpScribble. It is excellent value for money, easy to use and the support from Jan Goyvaerts has been first class. It imports .rtf and .hpj files from AccHelp without a hitch and makes both WinHelp and HTMLHelp plus other outputs.
Having said that, it is worth having a basic knowledge of how a WinHelp file is built and knowing that it is possible to do it using Word and the WinHelp Workshop.
WinHelp needs a minimum of two files and the WinHelp Workshop.
One is a RTF (Rich Text Format - suffix .rtf usually) file which you can create with Word, go here for the MS RTF specification. The second is the Help Project File (suffix .hpj) used by WinHelp Workshop to control compilation of the resulting Help File.
A third file though technically optional is necessary and that is a .cnt help contents file.
There are Macros and Add-Ins for Word to aid in the production of RTF help files. Note that Word actually produces monstrous RTF files, it piles font definitions and other stuff in like it's going out of fashion. That doesn't stop the RTF file from compiling but it does make big files with a load of redundant information in. If you want to see just how big they are, create a new document in Word with just a single short sentence in it, save it as RTF then open it in Notepad or some other text editor.
Go to the HelpMaster site to locate downloads (32 bit versions) of WinHelp Workshop and the WinHelp compiler. You may also find the WinHelp Decompiler useful for examining the structure of existing Help files.
Each Help topic in the RTF is on it's own page. Endnotes (a type of Footnote that appears at the end of the document rather than at the foot of each page) are used within the RTF to connect each Topic to an ID, this ID may or may not be the same as the HelpContext ID in Access.
Here's a very simple two topic RTF file I created by hand using the Text editor TextPad it's spread out to make reading easier and it does compile successfully to a HLP file:-
{
\rtf\ansi\deff0{\fonttbl{\f0\fswiss Helv;}{\f1\froman Tms Rmn;}}\sectd \pard\plain \fet1\aenddoc{\super #{\footnote\ftnalt \pard\plain \fs20{\super #}{100}}\pard\plain
OVERVIEW
\par
Written by hand with TextPad.
}\page{\super #{\footnote\ftnalt \pard\plain \fs20{\super #}
{200}}\pard\plain
DETAIL
\par
TextPad was used to manually create this endnoted Rich Text File}
}
Each of those TopicID's is itself mapped via the HPJ file. The MAP section of an HPJ file links the help topic ID's in the RTF to the HelpContextID's during compilation. HPJ files are help project files made by using WinHelp Workshop or by AccHelp. HPJ files control WinHelp Workshop (and the Help Compiler) and the production of WinHelp (suffix .hlp) files.
If you use the same numbers for topics in your RTF as the HelpContextIDs in your application, then the a MAP section in the HPJ file must equate them. For example if you had two forms with ID's 100 and 200 and two topics which you endnoted #100 and #200, you must have a MAP section that contains;
100 = 100
200 = 200
As mentioned above, traditionally you would create the RTF using Word, manually creating the # endnotes and so on. If you want search and keywords those are extra endnotes using $ and K.
AccHelp does all this for you automatically, creating .rtf and .hpj files that contain all the basic information ready for you to edit or import into a help authoring tool plus optional K and $ endnotes.
HTMLHelp File Production
This differs from WinHelp in a number of ways. The most obvious are;
- It uses individual HTML documents for each Help Topic.
- The final result is a compiled HTML file called a CHM.
- It is viewed with Internet Explorer which must be on every target machine.
It's well worth going to the MSHelpWiki and downloading then reading Char James-Tanny's HTML Help Workshop tutorial. For a fuller understanding it's also worth reading up on Topic ID mapping and aliasing.
So, whereas in WinHelp we had one RTF file with the Topic's each on their own page, here we have each Topic in it's own HTML file. We also have a project file for the help compiler as before, now called a .hhp file and we have a contents file .hhc and an index file .hhk.
Most of the problems I've seen others mention in the newsgroups appear to be to do with .dll versioning when using the more advanced functions. Others have reported that sometimes Help appears in the Access help window, sometimes it just loads a blank screen. I've not had these problems, but I do tend to keep HTMLHelp very basic without any pop-ups or anything other than simple text and screen shot help screens.
Perhaps I'm not trying hard enough.. :-))
More to come later - bear with me.
