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
We are therefore proposing to improve the way help works on the IYONIX
pc by making it more accessible and visually appealing, while retaining
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.
All applications intended for use on the IYONIX pc should be supplied with help in
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
To make it more accessible application help should be available as follows:
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.
- 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)
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
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
Set AppName$Dir <obey$dir>
Set AppName$Help <obey$dir>.Documents.index/html
if "<alias$@RunType_FAF>" <> "" then
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:
Application System Variables
Applications should set the following system variables as appropriate:
These variables should be set in the !Boot and !Run files. For example:
| ||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)
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:
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.
|© 2006 IYONIX Ltd
||32-bit RISC OS|