Today you will learn how to build help applications for your Visual Basic 5 database application. You will create help files in a standard word processor and attach them to your application. You will then see an application that can facilitate much of the work encountered in the creation of a help file.
To perform the exercises in this chapter, you will need a word processor that can save your data files in rich text format (RTF). Microsoft Word is an example of such a program. You will also need the help compiler HCW.EXE. This file ships on the Visual Basic 5 CD. The setup file for this program can be found in the \\TOOLS\HCW directory on the CD. If you haven't done so, go to the TOOLS\HCW directory and install this application.
Including online help with your Visual Basic database application is important for several reasons. First, online help makes your application look "finished." The user gains greater confidence in your application if there is an online resource that he or she can turn to for assistance.
Second, online help makes a system easier to use. Users don't have to search for printed manuals for answers to their questions. Researching information online is faster and easier than leafing through printed manuals. Users don't have to leaf through a table of contents or an index to get the appropriate answer. Instead, users can use the search feature of the online help.
Third, online help can be customized. For instance, users can enter their own comments using the Annotation function. This helps to inform others of policy decisions and system uses. It also helps in the use of the system across different functional areas.
You should also understand the drawbacks of using online help. Many users have not accepted the paradigm of searching for information online. Some users like to take manuals home with them on the weekend. Others like to write important notes in the margins of their manuals. Others find it a strain on their eyes to read long descriptions of information on-screen. Also, if the online help is poorly designed, users can get trapped in endless loops and not find the information they expect.
Overall, the benefits of attaching an online help file to your application far outweigh the drawbacks. Help of any sort, even if it is the name and phone number of the program developer, should be included with any application you develop.
You should follow these steps in order to build a help file for your application. (This lesson focuses on each step in detail.)
The first step in creating your online documentation is to create a topic file. The topic file contains the text that the user sees when he or she presses F1 in your application. This file also contains codes in the form of footnotes that the WinHelp program uses to determine how the system is to function.
We used Microsoft Word 7 in the development of this lesson's examples to create the topic file. If you are not using Word, make sure your word processor supports the following capabilities:
Before starting, make sure that your default system options are set so that you can view hidden text. In Word, select Options... from the Tools menu. Next, select the View tab. Then, under Non-printing Characters, check the Hidden Text checkbox.
You might also want to select the Print tab and then check the Hidden Text checkbox in the Include with Document section. This allows you to print any hidden text codes entered into your document.
As with good programming, it is important that you design your help file before you build it. The following exercises cover the design of the help file at the end. You will be much better at designing the help file after you have learned how it is built. Now let's build the topic file.
To start the project today, begin by building a text file that contains the information the user reads when help is requested. You will build a file to attach to the Company Master application you started in Week One.
Let's keep the text file short and enter only information for the three sections of the application: Company Information, Contact Information, and Other Information. Although you enter a small amount of information, it provides you with the skills you need to build help files of any size.
You should now enter into your word processor the text shown in Figure B.1. You
can find this text in the TOPICS.DOC file found in the \TYSDBVB5\SOURCE\APPXB\HELP
directory on the CD that ships with this book. You could also import TOPICS.RTF
into your word processing package if you are using a word processor other than Word.
Figure
B.1. The text for your sample help file.
Each topic in your text file must be separated with a hard page break. In Word,
you enter hard page breaks by pressing Ctrl+Enter. Now do this between each topic.
Your file should look like the one shown in Figure B.2.
Figure
B.2. The text file with page breaks between
the topics.
Now that the text entry is complete, you can start entering the format codes. These
codes inform the help compiler what to do with this text.
The context string is the unique identifier for a topic and serves as the unique key for the help system. Users do not see this code; it is only used by the WinHelp program for ordering the topics.
You need to insert a footnote to designate a context string for a topic. The footnote is marked with a pound sign (#). To insert a footnote, follow these steps:
Figure
B.3. The Microsoft Word Footnote and Endnote
dialog box, used for entering a custom footnote mark for a context string.
The footnote section of Word now appears. Type the context string CompanyInformation.
Be sure you have no more than one space between the # and the context string. Your
screen should now look like the one shown in Figure B.4.
Figure
B.4. Entering the context string.
When building the context string, it is important not to leave any spaces in your
text. Entering Company Information (with a space) results in a compile error.
It is also a good practice to match the context string as closely as possible to
the heading you place on each topic. This prevents confusion when dealing with a
large number of context strings.
The context string is the only required footnote for each topic. The following sections discuss optional help file footnotes that you should also include with each topic.
Now that you have entered the context string for the first topic, it is time to
enter the title footnote. The title is displayed as the topic in the Help Topics
Find tabbed dialog box of the help system. (See Figure B.5.) It's a good practice
to use the topic heading from the topics file as the title of the text for this footnote.
Figure
B.5. The Windows 95 Help Topics Find tabbed
dialog box.
Entering the title is similar to entering the context string. However, the title
footnote can include spaces between the words and is designated by the dollar sign
($) custom footnote mark rather than the pound sign (#).
Follow these steps in order to insert a title for the Company Information topic:
You can find help topics in the Help Topics dialog box by typing a keyword for a topic and then clicking the Display button. Determining which keywords apply to a specific topic is the focus of the next section.
Keywords are used in the WinHelp Help Topics Find tab to find topics. You use the same techniques for entering keyword footnotes as you did for entering context strings and titles. However, there are two differences: You can have multiple keywords for each topic (each keyword separated by a semicolon), and you use the uppercase letter K as the custom footnote mark for the topic.
Follow these steps in order to define a keyword for the first topic:
NOTE: It is possible to enter keywords for a topic and not a title. This results in an >>Untitled Topic<< message appearing in the Topics section of the Help Topics Find tab. To avoid this, always include a title if you use a keyword.
The last code to enter is the browse sequence. The browse sequence defines the order in which you can move through help screens by pressing the forward (>>) and reverse (<<) buttons at the top of your help screen. This footnote is defined by the plus sign (+), and it uses the following syntax:
group name:sequence
In this line, the group name is followed by a colon and then by the order in which the topic appears in the group. The group allows you to connect all related topics in the help file so that users can move forward and backward in order to review any related information. The sequence is the position of the topic within the group.
For this exercise, let's add a browse sequence for Company Information.
You have entered all the necessary footnotes for the first topic. Your screen
should now look like the one shown in Figure B.6.
Figure
B.6. All the footnotes for the Company
Information topic.
Continue this exercise by entering the footnotes for the other two topics in your
file. Use Table B.1 as a guide.
Table B.1. Footnote information for the contact information
and other information topics.
| Topic | Footnote Type | Code | Footnote Text |
| Contact Information | Context string | # | ContactInformation |
| Title | $ | Contact Information | |
| Keyword | K | Contact | |
| Browse sequence | + | Company:2 | |
| Other Information | Context string | # | OtherInformation |
| Title | $ | Other Information | |
| Keyword | K | Other | |
| Browse Sequence | + | Other:1 |
You should now save all of the information that you have entered into your topic file. First, save the information as a Word 6 document. To do this, select Save from the File menu. Save your information as TOPICS.DOC.
Now save the file as an RTF file. Do this by selecting Save As... from the File menu. Open the Save File As Type combo box and select Rich Text Format. Enter TOPICS.RTF in the File Name box. Then, execute the save by selecting Save.
When creating large help files, keeping track of the different footnotes can become quite cumbersome. For instance, all the context strings must be unique and the browse sequence must follow an order within each group. For just three topics, this is not a hard task. But for 50, 100, or 1000 topics, this task becomes much more difficult.
Therefore, it's recommended that you keep track of all the footnotes you enter for each topic in a spreadsheet. This helps you in establishing the browse sequence and ensures that each context string is unique. For each topic, keep the heading from the topics file as well as details on each footnote that you enter.
A tracking file also helps you build the project file, which is the subject of the next section.
When you have entered your help text in a document, inserted the appropriate footnotes, and saved the document as an RTF file, you are ready to build the project file. The project file tells the help compiler how to create a help file (HLP) from the topic file (the RTF).
The project file is very similar to an INI file. Enter information in sections, which each have a heading enclosed in square brackets ([ ]). These files can be created in a text editor and must be saved as unformatted ASCII text. Now open the Notepad accessory in Windows to create the project file.
Enter the following text to create the project file. Save your file into the same directory as your TOPICS.RTF file and name it PROJECT.HPJ.
; Project file for the Company Master Help ; [Options] Title=My Help File ;Title to Appear on the Help Title Bar ErrorLog = Error.TXT ;File to store compile errors [Files] Topics.RTF ;Name of the file containing the topics [Config] BrowseButtons() ;Macro to place browse buttons on the help screens [Map]; section to define context string parameters CompanyInformation 1 ContactInformation 2 OtherInformation 3
The first section of the project file is the [Options] section. This section, if used, should always be the first section of the topic file. Although it is not required that you use this section, it is highly recommended. This is where you identify the title that appears on your help title bar as well as the name of the file that is used to collect compilation errors.
Here is the syntax to follow when entering an [Options] section:
[Options] Title=My Help File ;Title to Appear on the Help Title Bar ErrorLog = Error.TXT ;File to store compile errors
The second section is the Titles section. This section is required in all project files. It contains the name of the topic file (the TOPICS.RTF file in this exercise) from which the help file is created. You entered only one line in this section:
[Files] Topics.RTF ;Name of the file containing the topics
The third section is the [Config] section. This section lets you declare macros to be executed when your finished help file is compiled. In the [Config] section you have entered a macro name that places browse buttons at the top of the help screen to aid you in moving through the defined browse sequences. For this section, enter the following:
[Config]
BrowseButtons() ;Macro to place browse buttons on the help screens
The final section in the exercise is the [Map] section. In this section, you enter numeric references to the context strings that you entered into the RTF file. Be very careful when building this section. Your context strings must be identical to the context strings entered in the RTF file. Enter the following:
[Map]; section to define context string parameters CompanyInformation 1 ContactInformation 2 OtherInformation 3
There are several other sections you can place in your project file. The [Buildtags] section, for instance, allows you to designate the topics in the RTF file that are to be compiled. There is also a [Windows] section where you can set parameters for the sizing, background colors, and locations of your help file.
You can also place an [Alias] section in your project file. Aliases allow you to assign multiple context strings to the same topic. This is useful when you delete topics in your RTF file. See the VB 5 Books Online, The Microsoft Help Compiler Guide, for a complete discussion on each of these sections.
Now that you have created your project file, it is time to compile your help application.
You should now start the Microsoft Help Workshop application to compile your project. Please note that you have to install this application from the Visual Basic 5 CD if you have not already done so. The SETUP.EXE file for the Help Workshop can be found in the \\TOOLS\HCW directory of the Visual Basic 5 CD.
Once you start the Help Workshop, select File | Open... and find the PROJECT.HPJ file you created in the preceding exercise. Enter the name of PROJECT.HLP in the Help File box at the top of the screen. Your screen should look similar to Figure B.7.
Now select File | Compile. This brings up the Compile a Help File dialog box. Select the Browse... button and find the PROJECT.HPJ file you created previously. Select the Compile button to begin the compilation of your help file. The result is a PROJECT.HLP file that can be accessed directly from the Windows Explorer, or by selecting File | Run Winhelp... in Help Workshop.
You are prompted for any compilation errors that are written to the error file
ERROR.TXT. Review any error messages you receive and then edit the project
and topic file as needed. Then you can recompile your project.
Figure
B.7. The Help Workshop application.
When the PROJECT.HLP file is created, it is ready to be attached to your Visual Basic database application. Before attaching it, however, let's first review the file. To do this, open the Windows Explorer, and then double-click the file PROJECT.HLP. The first topic, Company Information, should now appear.
You now attach the help file to the Company Master application that you've been working on in this book. To do this, you first attach help information by setting Visual Basic 5 control properties. After that, you use code to assign help definitions. When you have completed that, you add menu applications to the application that automatically bring up the Contents, Search, Help on Help, and About Help information.
Follow these steps to attach a help file to your project:
This assigns the help file to the project. You now need to assign the help context ID to the controls on the Company Master form. Follow these steps to make the attachments:
The entry in the HelpContextID property refers to the value you set in the project file (PROJECT.HPJ) for the context string.
Save your form and run the project. Click in the Company Name field and press F1. You should now see the help you wrote for the Company Information topic.
Now exit help and return to form design mode. Assign the remaining input fields within the Company Information frame to HelpContextID 1. Assign 2 to the HelpContextID property for all the fields in the Contact Information frame, and assign 3 to all the input fields in the Other Information frame.
Run the project and select any field on the form. Press F1 to bring up help. Select the Index button and then the Find tab. Notice that the keywords appear in the middle box and the titles appear in the lower box.
You can use the >> button in the Company Information topic to move to the Contact Information topic. This happens as a result of setting the browse sequence for both topics to the same group. Notice that Company Information comes first within this browse sequence. This is due to the browse sequence of Company:1 for the Company Information topic and Company:2 for the Contact Information topic.
While in help, select the Contents button. Company information should now be displayed. The Contents button displays the first topic in your help file if you do not declare a contents topic in your project file. Declaring this topic and building a contents page is the subject of the next lesson.
To build the contents page, you need to build a topic, assign footnotes, create jumps to the underlying topics, and modify the project file. When you have done this, you then need to recompile the project.
Reopen your topics file (TOPICS.DOC) and enter the following information for the contents page. Make sure that you insert a page break between the Other Information topic and your new topic.
Table of Contents This is the page we will use for our Table of Contents. _Select the topic you would like to view. Company Information Contact Information Other Information
You now add a jump to each of the three sections in the contents page. To do this, follow these steps:
Company InformationCompanyInformation
Use the following information to insert the footnotes for the Table of Contents topic:
| Footnote Type | Code | Footnote Text |
| Context string | # | TableofContents |
| Title | $ | Table of Contents |
| Keyword | K | Contents;Table of Contents |
Let's add one more feature to your topic file--a pop-up. A pop-up is a box of
text that displays on top of the active help topic. It is commonly used to provide
term definitions without requiring the user to select a jump to a different topic.
A jump should therefore be used to elaborate on the current topic, not to serve as
a topic itself. See Figure B.8 for an example.
Figure
B.8. A pop-up.
Adding a pop-up to your help topic is the same as adding a jump, except that you
use a single underline for the pop-up text rather than the double underline used
for the jump text. Follow these steps to add a jump:
Contact Person The person to whom we send monthly statements.
Footnote Type Code Footnote Text Context string # ContactPerson Title $ Contact Person Keyword K Contact
Contact PersonContactPerson
Figure
B.9. Adding a pop-up.
You have now completed the revisions to the topic document. Save this document in
RTF format. Also, save the document a second time in your word processor's normal
format.
You now need to make some changes to the project file. Remember that you created
this file earlier in the Notepad application and gave it the name PROJECT.HPJ.
Bring up Notepad and open this file. This file should look like the one shown in
Figure B.10.
Figure
B.10. PROJECT.HPJ, the
Project file.
You first need to edit the [Options] section to identify the topic you want
to use as your contents topic. Modify this section so that it looks like this:
[Options] Title=My Help File ;Title to Appear on the Help Title Bar ErrorLog = Error.TXT ;File to store compile errors Contents = TableofContents
TableofContents is the context string you assigned in the earlier exercise.
You also need to modify the [Map] section for the new topics you added. Change this section of PROJECT.HPJ so that it looks like the following:
[Map]; section to define context string parameters CompanyInformation 1 ContactInformation 2 OtherInformation 3 TableofContents 4 ContactPerson 5
You do not add a context string for the pop-up because you will not reference it from a Visual Basic control.
Save your changes to this file, and exit to the Microsoft Help Workshop, and then compile your help file.
When the file is successfully compiled, return to Visual Basic and run the Company
Master application. Select a control in the Contact Information frame and press F1.
Select the underlined phrase Contact Person. Your definition now appears (see Figure
B.11).
Figure
B.11. A pop-up definition.
Next, select the Contents button to display the Table of Contents topic. Select any
of the underlined items to jump to their topic. When you're in the topic, select
the Back or Contents button and return to the original screen.
In the previous exercise, you attached the help filename by entering it in the Project Options section and setting the HelpContextID in each control's properties. You can also set these values at runtime. Just enter the following code in the Form_Load procedure to open the help file and set help context IDs:
Sub Form_Load () `assign the help file App.HelpFile = "C:\TYSDBVB5\SOURCE\APPXB\HELP\PROJECT.HLP" `set the help context id for a control txtName.HelpContextID = 1 End
You need to set a HelpContextID for each control to which you want to add help. Be forewarned that this can be a very time-consuming chore if you have a large number of controls or a large number of forms in your Visual Basic database application.
You see Contents, Search, Help on Help, and About menu items on the Help menu of most Windows applications. The purpose of this exercise is to show you how to add these items to your Visual Basic database application.
Start by opening a new project and building the following menu by choosing Menu Editor... from Visual Basic's Tools menu:
| Menu Item | Name |
| &File | mnuFile |
| E&xit | mnuExit |
| &Help | mnuHelp |
| &Contents | mnuContents |
| &Search | mnuSearch |
| Help&onHelp | mnuHelponHelp |
| -- | mnuSep1 |
| &About | mnuAbout |
NOTE: The code in this example can either be entered manually or taken from the CD that ships with this book.
Now enter the following code in the Form_Load procedure of your HELPMENU.FRM file:
Private Sub Form_Load () `assign the help file to use (insert your path) App.HelpFile = "C:\TYSDBVB5\SOURCE\APPXB\HELP\PROJECT.HLP" End Sub
The line App.HelpFile = "C:\TYSDBVB5\SOURCE\APPXB\HELP\PROJECT.HLP defines the help file for the project.
Next, create a new module by selecting Add Module from the Project menu, name it PRCHELP.BAS, and insert the following code inside the general declaration section:
Option Explicit
#If Win16 Then
Declare Function WinHelp Lib "User" (ByVal hwnd As Integer,
_ ByVal lpHelpFile As String, ByVal wCommand As Integer,
_ ByVal dwData As Any) As Integer
Declare Sub ShellAbout Lib "shell.dll" (ByVal hWindOwner As Integer,
_ ByVal lpszAppName As String, ByVal lpszMoreInfo As String,
_ ByVal hIcon As Integer)
#Else
Declare Function WinHelp Lib "user32" Alias "WinHelpA" (ByVal hwnd As Long,
_ By Val lpHelpFile As String, ByVal wCommand As Long,
_ ByVal dwData As Any) As Long
Declare Function ShellAbout Lib "shell32.dll" Alias "ShellAboutA"
_ (ByVal hwnd As Long,
_ ByVal szApp As String, ByVal szOtherStuff As String,
_ ByVal hIcon As Long) As Long
#End If
Global Const HELP_QUIT = 2
Global Const HELP_INDEX = 3
Global Const HELP_HELPONHELP = 4
Global Const HELP_PARTIALKEY = &H105
Insert a new procedure by selecting Procedure from the Insert menu, name it HelpFile, and insert the following code:
Sub HelpFile (frmForm As Form, nHelpCmd As Integer)
Dim i As Integer
Dim nFlag As Integer
Dim aData As Variant
`
`Test for the naming of a help file
If Len(LTrim(RTrim(App.HelpFile))) = 0 Then
MsgBox "No Help File Available"
GoTo HelpFile_Exit
End If
`Set a text flag
Select Case nHelpCmd
Case Is = HELP_QUIT
nFlag = True
Case Is = HELP_INDEX
nFlag = True
Case Is = HELP_HELPONHELP
nFlag = True
Case Is = HELP_PARTIALKEY
nFlag = True
Case Else
nFlag = False `invalid command!
End Select
`Pass parameters to the DLL call
If nFlag = True Then
If nHelpCmd = HELP_PARTIALKEY Then
i = WinHelp(frmForm.hWnd, App.HelpFile, nHelpCmd, "")
Else
i = WinHelp(frmForm.hWnd, App.HelpFile, nHelpCmd, 0&)
End If
Else
MsgBox "Invalid Help Command Value"
End If
`
HelpFile_Exit:
End Sub
Create a new procedure by selecting Insert | Procedure and entering the following code:
Sub WinAboutPage (frm As Form) Dim MoreInfo$ ` MoreInfo$ = "Copyright " + Chr$(169) + " 1994 Software Company, Inc." MoreInfo$ = MoreInfo$ + Chr$(13) + "Technical Support: 800-555-7777" ` Call ShellAbout(frm.hWnd, app.Title, MoreInfo$, frm.Icon) End Sub
First, enter the following code in the mnuContents_Click event:
Private Sub mnuContents_Click () Helpfile Me, Help_index End Sub
Second, enter the following code in the mnuSearch_Click event:
Private Sub mnuSearch_Click () HelpFile Me, Help_PartialKey End Sub
Third, enter the following code in the mnuHelponHelp_Click event:
Private Sub mnuHelponHelp_Click () HelpFile Me, Help_HelponHelp End Sub
Fourth, enter the following code in the mnuAbout_Click event:
Private Sub mnuAbout_Click ()
WinAboutPage Me
End Sub
Fifth, enter the following code inside the mnuExit_Click event:
Private Sub mnuExit_Click() Unload Me End Sub
And finally, enter the following code inside the Unload event for your form:
Private Sub Form_Unload (Cancel As Integer) HelpFile Me, Help_Quit End Sub
Save your form and project. Run the project and select each of the menu items.
Notice that Help | Contents displays the Contents page of the help file you created
earlier today and declared in the Form_Load event. Selecting Help | Search
displays a listing of topics from the same help file. The menu selection Help | Help
on Help displays a screen similar to Figure B.12, which shows the Win 95 help topics.
Selecting Help | About displays a dialog similar to Figure B.13, which contains information
about your program. Finally, selecting Exit from the File menu stops the execution
of the program.
Figure
B.12. Help on Help.
Figure B.13. The About box.
You first began this project by entering code in the general declaration section for two API calls. The first call was made to the Windows help system to display the Help on Help, Search, and Contents information. The second call is solely for the About box:
#If Win16 Then
Declare Function WinHelp Lib "User" (ByVal hwnd As Integer,
_ ByVal lpHelpFile As String, ByVal wCommand As Integer,
_ ByVal dwData As Any) As Integer
Declare Sub ShellAbout Lib "shell.dll" (ByVal hWindOwner As Integer,
_ ByVal lpszAppName As String, ByVal lpszMoreInfo As String,
_ ByVal hIcon As Integer)
#Else
Declare Function WinHelp Lib "user32" Alias "WinHelpA" (ByVal hwnd As Long,
_ ByVal lpHelpFile As String, ByVal wCommand As Long,
_ ByVal dwData As Any) As Long
Declare Function ShellAbout Lib "shell32.dll"
_ Alias "ShellAboutA" (ByVal hwnd As Long,
_ ByVal szApp As String, ByVal szOtherStuff As String,
_ ByVal hIcon As Long) As Long
#End If
Notice that you used the compilation directive (#if) to insert the code so that this application runs under the 16-bit version of Visual Basic 4. You then used the #Else directive to insert the 32-bit version. By doing this, the application runs under either version of Visual Basic (16- or 32-bit), or Visual Basic 5.
The final entries into the general declaration section are to define the constants that are called by the Help menu items:
Global Const HELP_QUIT = 2 Global Const HELP_INDEX = 3 Global Const HELP_HELPONHELP = 4 Global Const HELP_PARTIALKEY = &H105
The HelpFile procedure performs the following tasks:
Sub HelpFile (frmForm As Form, nHelpCmd As Integer) Dim i As Integer Dim nFlag As Integer Dim aData As Variant
If Len(LTrim(RTrim(App.HelpFile))) = 0 Then
MsgBox "No Help File Available"
GoTo HelpFile_Exit
End If
Select Case nHelpCmd
Case Is = HELP_QUIT
nFlag = True
Case Is = HELP_INDEX
nFlag = True
Case Is = HELP_HELPONHELP
nFlag = True
Case Is = HELP_PARTIALKEY
nFlag = True
Case Else
nFlag = False `invalid command!
End Select
If nFlag = True Then
If nHelpCmd = HELP_PARTIALKEY Then
i = WinHelp(frmForm.hWnd, App.HelpFile, nHelpCmd, "")
Else
i = WinHelp(frmForm.hWnd, App.HelpFile, nHelpCmd, 0&)
End If
Else
MsgBox "Invalid Help Command Value"
End If
HelpFile_Exit:
End Sub
The WinAboutPage procedure makes an API call to display an About box. Parameters are passed for a company name and a technical support number:
Sub WinAboutPage (frm As Form) Dim MoreInfo$ ` MoreInfo$ = "Copyright " + Chr$(169) + " 1994 Software Company, Inc." MoreInfo$ = MoreInfo$ + Chr$(13) + "Technical Support: 800-555-7777" ` Call ShellAbout(frm.hWnd, app.Title, MoreInfo$, frm.Icon) End Sub
The Click events for the menu items are defined to call the HelpFile procedure and pass the appropriate parameters:
Sub mnuContents_Click () Helpfile Me, Help_index
End Sub
Sub mnuSearch_Click () HelpFile Me, Help_PartialKey
End Sub
Sub mnuHelponHelp_Click () HelpFile Me, Help_HelponHelp
End Sub
Sub mnuAbout_Click ()
WinAboutPage Me
End Sub
Sub mnuExit.Click() Unload Me End Sub
Finally, when the form unloads, housekeeping should be performed and any help screens that have been left open should be closed. This is the role of the Form_Unload event.
Sub Form_Unload (Cancel As Integer) HelpFile Me, Help_Quit End Sub
Please note that Unload Me was used in the Exit menu item rather than End. Using the End command would stop execution of the program without triggering the Unload event.
There are commercial products available that greatly reduce the time required for developing a help file. These products automate the process by which footnotes are entered, context strings are mapped, project files are built, and the help file is compiled. In addition, these programs can "strip" footnotes from your topic file so that you can use it for your printed documentation.
There is a tradeoff that you should be aware of when using an authoring tool. Any tool undoubtedly makes you more efficient in the creation of topic files; but if it takes you more time to install and learn the product than you save by using it, you are better off producing the file manually.
The ultimate determinant in whether or not to purchase a help authoring tool is based upon the size of your projects. Simple one- or two-screen applications are probably best documented manually. More complex, multiscreen applications will best be documented with the assistance of a help authoring tool.
There are numerous authoring tools available. They range in price from approximately $100 to $500. Many of these products must be purchased directly from their authors. It is hard for us to recommend one specific help authoring tool over another because your own personal working habits dictate which tool is best for you and your project. Please consult the advertising found in the back of trade publications to obtain the distributors, pricing, and titles of the latest authoring tools.
In order to learn how these tools operate, you might preview an intriguing authoring tool available free of charge from Microsoft. It is called WHAT6.EXE. This file can be obtained from the Microsoft Web site, CompuServe, and America Online services. This tool is actually a Word document template that contains a series of macros that assist in the building of topic files. It is unsupported by Microsoft, which means you have no one to turn to if you have a problem or a question. Weigh this factor very carefully before you decide to utilize this tool on a live project.
Let's turn to the design of your help application. As demonstrated in the exercises for this lesson, your help topic file contains the information that users depend upon to operate your application. An effective help system must be designed properly to meet the users' needs.
Make sure you understand who will be using your system. For instance, you would design and write one type of help topic file for highly sophisticated users and another for novice users. Different levels of users have different technical needs and viewpoints concerning the use of computers as productivity tools. Meet the expectations of your users, both technically and emotionally.
Always plan what you will include in your help system. Don't begin writing until you have given consideration to the detail you want to provide and the browse sequences you want the user to see. Plan your topics to be no more than a few pages long. The topics should also be more than a sentence or two in length. You will find it better to use one topic that is two pages long in order to describe every field on a report, rather than writing many short topics in order to explain each control.
Keep the design of your help system simple. Also, be sure to use jumps judiciously: You don't want your users jumping through page after page of information. It is better to duplicate help information rather than have the user continually jumping from screen to screen in order to find the answer to a simple question.
Don't try to model your users' business practices when building the topic file. Your system should be designed to be versatile, allowing for changing environments. Your help system should follow the same thought processes. Don't dictate how the system should be used optimally, but rather show the users how to do what they need to do. You will be surprised by the clever ways in which a well-designed system can be used.
Don't burden the users of your system with the obvious. For example, don't tell the users to enter a phone number in a field with a label Phone Number and an input mask of (###) ###-####. Everyone knows that this means to enter a phone number. Not everyone will know, however, where this number is used throughout the system or on what reports it appears. Be informative and follow through to the end. Don't stop your explanation when only 75 percent of the process has been defined.
It is best to write your online documentation as you build your system. Help files should be read and reviewed for suitability as part of the testing cycle. Writing the topic file as you code keeps you from forgetting key features of your design. Functionality is best documented when it is fresh in your mind.
Remember to budget time in your system design plan to write your online documentation. Writing is hard work and requires patience, perseverance, and attention to detail. Allow time for numerous rewrites and edits. Many experienced technical writers estimate that it takes approximately one hour to type a page of text. Make estimates based upon this rate and then adjust it according to the speed at which you work. Double the result that you get to allow sufficient time if you run into any problems.
Do not release a programming project that has not been properly documented. It is a mistake to think that you can provide quality documentation at a future date if you can't provide it at the ship date. A help system is needed most when users are new to the system and just beginning to learn it. Everyday work demands can distract you from the "less important" and routine responsibilities of your job. Always remember that creating a new project is exciting, but writing about a new project is often quite tedious. Discipline on your part is required in order to get the job done.
If you are managing a team of developers, allow them the time needed to develop docu-mentation. There are no shortcuts in system development or documentation. Items that are not finished when they should have been always come back to haunt you to an even greater extent some time in the future.
Know your writing abilities and seek assistance when needed. Many system programmers find it difficult to write. Their expertise lies with system design and coding, not with writing. This is not a bad thing in itself, as long as you are honest with yourself and are not ashamed to seek out technical writers for assistance.
Determine whether you will have both written and online documentation. You should provide both forms of documentation. It is easier to write the online documentation first and then use it as the starting point for your printed documentation. The online documentation follows the natural flow of the system.
Remember that users depend on your documentation to enable them to understand how to operate the systems that help them perform their jobs. You have a great responsibility to properly document your system and to make it easy to use and quick to learn.
Every application should have a help file attached. A help file ensures that the system is used as it was intended. It also gives the application a more "finished" look and feel.
The following key points were covered in this lesson:
