In the last few years, Geographic Information System (GIS) technology has been slowly, yet surely, weaving its way into mainstream business processes. The desktop GIS has developed to the point where a GIS application is becoming as acceptable and normal on PC desktops as word processing and spreadsheet programs. While GIS is showing up on many desktops, the concept of GIS is still very foreign to many people. Many new users tend to think that a GIS is "maps." When these users are provided with a sophisticated GIS-based application, if they are not given detailed instructions and adequate help, they may become hesitant to utilize the delivered application. As more and more people are utilizing a GIS on a daily basis, it has become a de-facto standard that desktop GIS applications include very detailed instructions and help files to support customers.
This paper will explore one method of providing custom on-line help, detailing those issues that are involved in setting up a custom on-line help file with ArcView. It will provide a basic outline for authoring and integrating custom help into ArcView. In addition, it will examine the benefits of having custom application on-line help, provide tips for the help authoring process, and detail how to integrate the help with ArcView. Finally, it will examine the use of on-line help to support application training.
Development of On-Line Help
Two types of help will be considered for this paper:
The figure below highlights both types of help.
Depending upon the type of application and the delivery requirements of your customer, help files may need to be developed prior to the final delivery of the product. While this may not be the most efficient manner to develop help, it may be a requirement of the customer, so it is best to determine up front from your client when help files must be operational. Many customers will want to see all aspects of an application, including help files, during the acceptance phase of the software development cycle. The danger of developing help files prior to acceptance or testing is that many times software deficiencies must be corrected and/or functionality must be altered. This can lead to having to rewrite the help files because of last minute functional or operational changes. Therefore, it is best to determine when and what type of help is required during the needs analysis and functional requirement gathering processes.
How Do I Get Started?
The best place to start developing your help is to review the functional requirements. What are each of the custom menus, buttons, and tools supposed to do? Are there procedural requirements for using the application? Do users have to complete several steps prior to utilizing a function or a process? The best idea is to review each of the custom buttons, tools, and menus and to sketch the procedures that must be followed to use the tool. This can be very useful if you are developing procedural help files that will provide a brief tutorial to users delineating the required steps and procedures that they must follow.
A useful procedure is to present the application without the help files to potential users for their review. Based on this review, the areas on which to focus the development of the help files can be determined. Another method is to present the application to a test team or a quality control group without providing them any instructions. If the help files are "user-friendly," then these users should be able to have any of their questions answered without human intervention.
Organizing the Help File
Once the needs for the help files are determined, the next step is to organize the files and to create an outline of the high-level topics. These topics will be presented to the user when the "contents" tab is pressed. The most frustrating aspect of using an application for a user, after they have determined that they need help, is spending an inordinate amount of time navigating a help file to find the topic that they are interested in. The typical Windows95
ã -type help has built-in "search engines," but it can still be frustrating to search for a topic. Organized "books" and "topics" will help alleviate the user’s frustration.An example of organizing the "books" and "topics" is shown below.
Once the major and minor topics have been determined, the help authoring process can begin. Based on the requirements of the application, you should base your help file content toward any potential or predetermined users. If the users are computer literate, you may base your help on technical issues and provide an explanation of the menu or tool. If your users are less knowledgeable about GIS, you may base your help on providing more thorough explanations and providing procedural steps to accomplish the desired results. Most help files tend to be targeted toward a variety of user levels, providing both procedures and steps, as well as technical explanations.
During the authoring process, you should determine if your topics will include pop-ups – topics that bring up more information when selected – or if they will include jumps – topics that navigate to another section of the help file. Utilizing these features will aid the user-friendliness of the help file. The more you design and organize the files, the less time you will spend creating them.
If your help files will include graphics, such as screen shots, menus, buttons, or tools, you should capture all of these graphics prior to developing the help file. By utilizing a standard naming scheme, it will aid you in retrieving these graphics for inclusion in the help file. One organizational strategy is to name the graphics appropriately and organize them into directories, including screens, menus, buttons, and tools (i.e., all screen shots go into screens, buttons into buttons, etc.). Each of the menus, buttons, and tools receive a name that will help you easily identify the graphics when you retrieve them. For example, if you are utilizing a button that invokes a map plotting tool, the graphic for that button could be named "map_button." The amount of effort to organize the graphics may be too time consuming for small projects; however, if you are developing a sophisticated application, and you have several menus, buttons, and tools for each type of document (e.g., View, Table, Layout, and Chart), you can become inundated with graphics for every custom feature. It is best to organize the graphics to provide an easy way to retrieve them.
Prior to deploying the application with on-line help, several items, as outlined below, need to be resolved.
Integrating Help into ArcView
Integrating your help file into ArcView is a very straightforward process. Each of the buttons, menus, and tools that come with standard ArcView have an associated "Help Topic." These topics are utilized when the Context Sensitive Help button is utilized. In the example below, the chosen button has a Help Topic called "My_Custom_Help @myhelpfile.hlp," which tells the help tool that when a user clicks on the Context Sensitive Help tool 
and then clicks on this button, this help file and topic will be invoked. The organization of your help file into topics and books, giving them intelligent names, is important because these names will be utilized by ArcView in navigating to the correct topic.
The help file name is myhelpfile.hlp. To ensure that the application can find the help file when it is invoked, you should include the directory of the help file in your PATH environment variable. The application will search throughout all directories in your path. The other option you can do is to either hardcode the path or utilize environment variables to locate the help files. The easiest method is to include the help file location in your path.
If you are developing an extension for your custom application, you will most likely want to include the help file as part of the extension, then you can use an environment variable to locate the help file. For example, your help topic with an extension would most likely be $USEREXT/myhelpfile.hlp or $AVEXT/myhelpfile.hlp, depending on where the extension is loaded. To invoke the help file from a menu, you need to identify the help file and set it as the "current help file." To invoke the help file called "GIS Data Browser Help," use the sample code provided below.
'' Set up local environment variables
'-----------------------------------------------------------------
theVar = "BROWHOME"
BROWHOME = System.GetEnvVar(theVar)
if (BROWHOME = nil)
then
MsgBox.Error("BROWHOME environment variable not initialized, exiting","Error")
exit
else
end
theHelpFile = BROWHOME+"\browser.hlp"
av.Help.SetFile(theHelpFile.AsFileName)
av.Help.SetTitle("Data Browser Help")
av.Help.Show
This code should be compiled into a script and then utilized to invoke the help file. The invocation of the help file will bring it up.
Using Help to Support Application Training
The use of on-line help for application training can be a very useful tool for providing users the necessary procedures for utilizing the software. Several Commercial Off-The-Shelf (COTS) products utilize "tutorials" for their software that give users a brief introduction into the features and functions of the software. If the requirements of your custom application require training prior to its deployment, you should consider using on-line help to accomplish this training. One software package, RoboHelp 4.0
ã from BlueSkySoftware, provides a method to print out the help file into a neatly organized printed document, which you could utilize for classroom instruction. The items that were covered in the training session will also be available on-line for the users. This is a very complete way to distribute your software since users often refer to the training sessions for more detailed instructions.While it is not necessary to deliver and distribute your training materials with the application, you should consider this, as it will reduce the amount of technical support required by your users.
Conclusion
The difference between a state-of-the-art application and a run-of-the-mill application can be directly attributed to the amount of effort that is put forth in developing, organizing, and presenting the application. It is important to have a well-designed and organized help file. As outlined in this paper, the organization of the help file prior to its development and deployment is critical. The delivery of self-sufficient and self-supporting applications to your clients is vital to their success. Help files are an integral part in accomplishing this effort.
Mark Ellis
Senior Software Engineer
Convergent Group
6200 S. Syracuse Way, Suite 200
Englewood, Colorado 80111
Phone (303) 741-8400
Mark.Ellis@cvg-grp.com