Help System

Introduction

Good help systems make software easy to use and increase user's satisfaction (or at least, reduce their frustration). Other platforms offer sophisticated help systems which make our traditional !Help text files look rather basic.

We are therefore proposing to improve the way help works on the IYONIX pc by making it more accessible and visually appealing, while retaining backwards compatibility.

Developers are encouraged to provide meaningful interactive help messages within their applications. The help should explain the function of a control and not simply explain that clicking on a check box will enable it without explaining what the function does. Messages such as 'Click Select to enable obscure feature X' , or even worse the infamous, 'Click select to not select feature X' .

Applications should provide a !Help file which can be accessed from the filer and it should also be accessible from the application's icon bar menu. In RISC OS 5 pressing menu over an application on the pinboard will show a Help menu item to access the !Help file if one exists.

HTML Help

All applications intended for use on the IYONIX pc should be supplied with help in HTML form.

HTML format help has many benefits over plain text:

Multiple fonts and text sizes can be used to make headings stand out
Hyperlinks can be used in contents pages and indexes and for cross-references
Help files can reference help files belonging to other applications
Pictures and diagrams can be included

Accessing Application Help

A large number of RISC OS users are unaware that application Help can be accessed from the application in the filer window. This is understandable, as most users load applications by double-clicking a particular file or by launching it from the pinboard - only rarely do users see applications in a filer window.

To make it more accessible application help should be available as follows:

Filer's App -> Help menu (as now)
Application's icon bar menu - Help should be second item, below Info
Application's main menu - Help should be last item in main menu
F1 key (on the IYONIX pc this will be labelled Help as well as F1)

Each of these options should open the application's help at the first page, unless something was selected, in which case it may offer context sensitive help, if available.

The position of the menu items have been carefully chosen. Icon bar menus always open with the pointer at the bottom of the menu with Info at the top and Quit at the bottom. By making Help the second item, it is quite obvious; it is well away from Quit so it is unlikely that Quit will be clicked by mistake and no extra mouse movements will be required to access existing menu items (other than Info which is rarely used).

Several applications already provide Help below Info on the icon bar menu, including Marcel and the new versions of FTPc, PDF, Caller Display and Teletext+.

Similarly, Help should be available as the last item on the application menu. These menus open with the pointer over the first item and the most common items near the top of the menu. By making Help the last item in this menu means that users will not find any current items displaced. Users should soon learn where to look for Help if it is always the last item on the menu.

Some applications including Impression Style and Publisher already provide Help as the last item on the main menu.

It was felt that Help is important enough to justify it's inclusion on the main menu rather than a sub-menu where it may not be found.

Where multiple help pages are available the application may provide a Help sub-menu, allowing the user to pick a particular topic from the Help menu item, but clicking on the Help item without opening its sub-menu should always open the main help file.

Providing Text Help

Some older systems may not have a web browser available, so it is recommended that applications provide help in plain text format as well as in HTML format.

The applications !Help file can be set up to open the HTML file where an HTML browser is available, and fall back to plain text format where there is no browser. This is achieved by making !Help an obey file with the following contents:

  Set AppName$Dir <obey$dir>
  Set AppName$Help <obey$dir>.Documents.index/html
  if "<alias$@RunType_FAF>" <> "" then 
    filer_run <appName$dir>.Documents.index/html
  else
    filer_run <appName$dir>.Documents.index/txt

The last four lines forming the if statement should be entered as a single line - they have just been separated here for readability.

The help menu items and F1 key should use the same mechanism to open the help text and this is best achieved by making these execute the !Help file:

Filer_Run <MyApp$dir>.!Help

Application System Variables

Applications should set the following system variables as appropriate:

		`AppName$Help`		Full pathname to HTML help file
		`AppName$Version`		Application's version number
		`AppName$Web`		URL for application's home page on the World Wide Web
		`AppName$Title`		Application's full title
		`AppName$Publisher`		Application's publisher
		`AppName$Description`		Concise description of the application
		`AppName$Running`		Set to Yes when the application is running (as defined in RISC OS 3 PRM page 4-497)

These variables should be set in the !Boot and !Run files. For example:

  Set AppName$Help <obey$dir>.Documents.index/html
  Set AppName$Version "2.72"
  Set AppName$Web "http://www.octosys.co.uk/cid.html"
  Set AppName$Title "Caller Display"
  Set AppName$Publisher "Octopus Systems"
  Set AppName$Description "Telephone call management - displays 
      and logs incoming and outgoing telephone calls."

These variable may be used to provide cross-references from other documents and also for a global help system which lists all help available on the system. It may also be used by a search system which can search and index all of the available help.

Cross references can be achieved as shown in the following HTML fragment:

You can upload files to the web server using the <a href="file:/<FTPc$Help">FTPc application</a>

This method of linking can be used in Browse, Fresco and Oregano.

Directory and Filenames

It is recommended that help files are located within a Documents directory within the application directory. The HTML help file should be given the name index/html and a plain text version should be called index/txt. A side-effect of this naming strategy is that the documentation files can be viewed on a PC or other system, and this may be useful if the user is having difficulties installing the software.

The application directory structure should look like this:

    !Application
          !Boot
          !Help
          !Run
          !RunImage
          !Sprites
          !Sprites22
          Documents
              index/html
              index/txt

Other Considerations

A tool to search HTML help files would be useful, especially if it could be accessed from within the web browser. Ideally a cached index should be available to improve search response times.

Another variable could be used to indicate that the user prefers plain text help files. The !Help file would check this and use plain text if requested. It is felt that this is unnecessary as the vast majority of users will welcome HTML help.

Help pages should look consistent between applications - using similar styles and text sizes as far as possible. We hope to release a suitable HTML template soon.