In this section, techniques for producing a well documented EASAP will be presented. These techniques will focus on three areas:
Producing an EASAP with readily available, high quality documentation is one of the keys to it being easy to learn and use. Therefore, authors should plan to document their EASAPs properly.
The faster a user can get to useful, helpful information about how an EASAP works, the faster a user will learn to use it. While providing good help files accessible from the Help button or Help menu is essential, providing helpful messages right on the EASAP’s user interface is even better since it removes a step for the users.
One of the most important aspects to creating helpful, easy-to-use EASAPs is the use of good labeling techniques. Labeling is required in many areas in an EASAP’s user interface. Some examples of these locations are as follows:
How well a user can understand the labels on the user interface of an EASAP will most likely have a strong correspondence to how well they can learn to use the EASAP. Several suggestions and guidelines around labeling are presented at Labelling Issues.
Another way to provide on the spot help to users is by making use of TEXTAREA object. Unlike object labels, the use of TEXTAREA is optional, but their use can greatly enhance the usability of an EASAP. Basically, a TEXTAREA allows you to place useful information right were users will need it, and possibly answer their questions right as they arise.
The ability to display tool tips is available as a parameter in most GUI objects. The Tool Tip parameter is optional in all cases. Taking the time to use it will provide your users with more useful information closer to where they need it.
Tip: If you do make use of the Tool Tip parameter, do not just repeat the label for the data entry box. Value is only added if new, more detailed information is made available to the user.
Another way to acquaint users with your EASAP is to make use of the Application Information parameter in the APPLICATION object. This parameter allows you to specify a file that can be opened and viewed by users from the Application Library before even opening the EASAP itself. The information contained in this file should let users know what to expect from the EASAP. It should tell them things like:
The file might be the same image used in your Overview pane or the same file as your help file. It may be an existing document currently used to describe the methods of the EASAP’s underlying software application. A variety of file types can be supported by browsers for use in the Application Information parameter, including HTML, PDF, GIF, and JPEG. When a file is specified, the display of the selection image for the EASAP is modified to include an information button as shown below.
To better acquaint users with your EASAP, you can make use of an “Overview pane” to provide some basic information about the EASAP. An Overview pane should be the first tabbed pane that users encounter when they open an EASAP. This pane should contain only background or overview type information about the EASAP and no data entry objects. The content of the Overview pane can be the same as the Overview section of your help files (see below). The form of this content will be an image file containing a screen capture of the overview text displayed within a word processor, text editor or browser.
An example of what the image file containing the screen capture of the overview content might look like is shown below.
The way that you create an Overview pane is as follows:
Once you have made your EASAP as easy to use as possible, it may still be very important or even essential to provide additional help in the form of a help file. Users might like access to information like:
* Background or historical information on why the EASAP was produced * Theory or mathematical equations used in underlying software applications * Details about how each user input is used by the underlying software applications
Typically this information is better suited for placement in a help file than on the user interface of the EASAP. All EASAPs created in EASA have a placeholder built-in for your help file. The current requirement is that your help files be written in HTML. The following sections will provide guidance on how to create your help files.
The first thing to know about your help files is that your main help file must be called: help.html. Since these files are written in HTML, hyper linking between more than one file is supported. Therefore, the help.html file can be thought of as your help file home page, with any additional files being linked to this page using hyperlinks. The next thing to know is that after creating your help files, you must upload them onto the EASA Server using the Files page found under the Authoring menu in Author mode. Users will have access to these files by either selecting ‘EASAP Help …’ under the Help menu.
Once a user requests the help pages for an EASAP, these pages are presented in a browser window like the one shown below.
Currently, EASA does not contain a tool for producing HTML directly, and therefore, it is up to the author to produce their HTML help files outside of EASA. There are a couple of options available for producing these files:
Since Option 1 requires that you must know or learn HTML, Option 2 is often the most convenient choice. The rest of this section will focus on using an HTML capable word processor including an example using Word. While using a word processor will be convenient and potentially straight forward to use for generating HTML, there are a few issues of which you should be aware:
The following example will provide instructions on how to create an HTML help file using Microsoft Word after typing the Help file content. An example of what this content might look like is shown below:
Overall, the level of detail that you will need to include in your help files will be determined by a couple of key factors:
Before being ‘able’ to use an EASAP, users also need to ‘want’ to use an EASAP. If your targeted users are choosing not to use the EASAP that you produced for them, you may want to improve your help files by better explaining:
If after deciding to use an EASAP, users have trouble using it, you can do a couple of things to alleviate their problems. Either improve the user interface of the EASAP or provide more guidance in the EASAP’s help files, or probably some of both.
The following sections offer suggestions for possible content within your help files. The aim is for you to create help files that bolster your users’ confidence in both their use of an EASAP and the results generated by it.
It is typically a good idea to start any document with some sort of overview, abstract, introduction or some similar type of section. The idea is to provide some basic information about the EASAP to the user very quickly. This basic information might include:
It might also be useful for you to provide your contact information, so users know how to contact you if they encounter problems or have questions. The hope is that this section will be sufficient for you to convince the appropriate people to use the EASAP.
Once a person has decided to use an EASAP, they will need to know how to do it. If they are unable to figure things out on an EASAP’s interface, they will probably look to the help files for assistance. The second section of your help files should address the ‘how to use’ issue. Here, instructions can be provided that lead users step by step through the use of the EASAP.
For users to not only just know how to use an EASAP, but to know how to use it properly, it may be necessary to provide some additional details about each of the inputs asked of them. You might want to provide information on:
The aim of this section will be to provide information to maximize proper use of an EASAP.
Several other sections might be included beyond the three main sections described above. It may prove useful to include sections such as:
You may decide the types of information described above may be useful, but do not warrant their own section. The EASAP Overview section can be a good generic section for inclusion of these types of information.