In this section, techniques for producing a well documented EASAP will be presented. These techniques will focus on three areas:

1. Labeling and help available on the User Interface of an EASAP
2. Creating EASAP Help files
3. Creating EASAP Introduction pages

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:

• Tab label on TABBED PANE
• Labels next to data entry boxes, such as CHOICE LIST, REALBOX, INTEGERBOX, TEXTBOX and LOGICBOX
• Border labels on SUB PANE
• Text annotation in diagrams

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:

• What type of information is generated by the EASAP
• How long does it take to run
• What data do they need to run it properly

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:

1. Add a TABBED PANE object as the first tabbed pane below the TABBED PANE LIST object, and set its Tab parameter to ‘Overview’.
2. Create a new DIAGRAM object on the DIAGRAM LIST sub-branch.
3. Add an IMAGE object to this new Diagram as a child object, and set its parameters as follows:
   • Image = image file name containing the overview text screen capture.
   • Size = Width and height in pixels of image file
   • Origin = 0,0
   • Define in Pixels = TRUE
4. Select the Tabbed Pane object created in Step 1 and set its Diagram parameter to the diagram name created in Step 2.

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:

1. Edit an existing HTML file or type in all the HTML code using a text editor.
2. Use a word processor like Microsoft Word or OpenOffice / LibreOffice that can export files in HTML format.

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:

• Some features such as exotic text formatting and tables may be modified undesirably when translated to HTML
• New folders or sub-directories may be created to contain additional files, such as image files (GIF, JPEG), used within the HTML file. To be used in EASA, these sub-folders must be uploaded onto the EASA Server along with the HTML file.
• Word processors may use code other than plain HTML, such as XHTML or XML, when translating the file contents. In this case, some features of the file may be lost or modified in translation when used as a help file in EASA.

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:

• Start Microsoft Word and open your Help file document.
• First we will create a ‘hyperlinked’ Table of Contents section. A prerequisite for this step is that a bulleted or numbered list of Help file sections has been created at the top of the file. You will first highlight a bullet item in the Contents section, for example 'Overview', with your mouse, and then click on the Insert menu and select Hyperlink (or type Ctrl-K).
• Next, a pop-up window will come up which can vary somewhat depending on your version of MS Word. A window similar to the following will appear upon requesting a hyperlink:

• You will be setting your links to a 'Place in This Document'; therefore, click on the 'Place in This Document' button on the left side of the window. The pop-up window will now appear as:

• Expand nodes on the tree until you see the relevant sections of your help file document, then select the section on the tree corresponding to the highlighted bullet item in the Table of Contents, for example ‘Overview’. Click on OK. The highlighted bullet item should be now in blue underlined text and be a hyperlink.
• Repeat Step 2 for the all other bullets items in the Table of Contents.
• Next, you will save this file as HTML. Under the File menu, select 'Save as …' and in the pop-up window, set the 'Save as type:' to 'Web page (*.htm, *.html)' and then set the File name to 'help.html'. Finally, choose a directory on your hard drive in the 'Save in:' box and click on 'Save'.
• If you haven't already, start EASA, log in, and Set Mode to Author.
• Under the Applications menu, select 'My EASAPs' and find the EASAP for which the new help file is intended.
• When you find it, click on its title link or selection image.
• Under the Authoring menu, select 'Files'. Click on the 'Browse' button to the right of the 'File to upload:' input box. Select the directory on your hard drive where you saved the ‘help.html’ file in Step 5 in the 'Look in:' box on the pop-up window. Then select the file, 'help.html' and click on the 'Open' button. Finally, click on the 'Upload' button back in your EASA browser window. The 'help.html' file will be added to your Current Files table.

Overall, the level of detail that you will need to include in your help files will be determined by a couple of key factors:

• The users’ familiarity with and confidence level in the methods used to generate results with the EASAP, and
• The EASAP’s ease of use.

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:

1. the types of results users can expect to get, and
2. the methods used to produce these results for them.

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:

• What it does,
• Who should use it, and
• Why you should use it.

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:

• What is really being asked for as input
• What type of data is expected
• How and where they can find the data being requested
• The reasoning behind any upper and lower bounds applied to an input
• Any rules of thumb that can be applied to deriving input values, potentially based on other input values

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:

• Background section - to provide historical details of why and how the EASAP was created
• Theory section - to provide mathematical equations, fundamental principles or laws, and any assumptions used by the underlying software applications in the EASAP
• Software section - to provide information about the quality and pedigree of the underlying software applications being used in the EASAP
• References section - to provide references of further reading for users to obtain even more relevant details

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.