Natural-language and speech interface systems

Natural-language and speech interfaces are coming into use. Unlike menu-driven systems and WIMPs, WYSIWYG and GUI type systems, the options are not normally defined on a screen. There may be many options.

For natural language and speech interface systems, the SUM should provide:

• a full list of facilities, explaining their purposes and use;

• examples showing how the facilities relate to each other;

• a list of useful command verbs and auxiliary words for each facility:

• a clear statement of types of sentence that are NOT recognised.

Embedded systems

Software that is embedded within a system may not require any human interaction at the software level. Nevertheless a SUM must be supplied with the software and provide at least:

• an overview;

• error messages:

• recovery procedures.

EVOLUTION

The development of the SUM should start as early as possible. Establishing the potential readership for the SUM should be the first step. This information is critical for establishing the style of the document. Useful information may be found in the section 'User Characteristics' in the URD.

The Software Configuration Management Plan defines a formal change process to identify, control, track and report projected changes when they are first identified. Approved changes to the SUM must be recorded by inserting document change records and a document status sheet at the start of the document.

74 ESA PSS-05-05 Issue 1 (May 1992) THE SOFTWARE USER MANUAL

The SUM is an integral part of the software. The SUM and the rest of the software must evolve in step. The completeness and accuracy of the SUM should be reviewed whenever a new release of the software is made.

RESPONSIBILITY

Whoever writes the SUM, the responsibility for it must be the developer's. The developer should nominate people with proven authorship skills to write the SUM.

MEDIUM

Traditionally, manuals have been printed as books. There are substantial advantages to be gained from issuing manuals in machine-readable form. tmplementers should consider whether their system would benefit from such treatment. Two possibilities are:

• online help;

• hypertext.

There should be specific requirements in the URD and SRD for online help and hypertext, since their implementation can absorb both computer resources (e.g. storage) and development effort.

Online help

Information in the SUM may be used to construct an 'online help' system. Online help has the advantages of always being available with the system, whereas paper manuals may be mislaid. Three possibilities, in order of increasing desirability are:

• a standalone help system, not accessible from inside the application:

• an integrated help system, accessible from within the application;

• an integrated, context-sensitive help system, that gives the help information about the task being carried out.

In the last option, the user should be able to continue the search for help outside the current context (e.g. to get background information).

ESAPSS-05-05 Issue 1 (May 1992) 75 THE SOFTWARE USER MANUAL

Hypertext

A hypertext is a structure of pages of text or graphics (and sometimes of other media). Pages are linked by keywords or phrases. For example, the word 'file' might give access to a page containing the words 'store', 'search', and 'retrieve'; in turn, each of these might give access to a page explaining a command within the documented system. Keywords may be displayed as text (usually highlighted), or may be indicated by icons or regions of a diagram which respond to a pointing device (such as a mouse).

Hypertext readily accommodates the hierarchical structure of most programs, but it can equally represent a network of topics linked by arbitrary connections.

This gives hypertext the advantage of a richer patternof accessthan printed text, which is inherently linear (despite hypertext-like helps, such as indexes).

Hypertext is also good for guided tours, which simulate the operation of the program, while pointing out interesting features and setting exercises.

The quality of graphics within a hypertext must enable tables, charts, graphs and diagrams to be read quickly and without strain. Older terminals and personal computers may not be suitable for this purpose. Modern bit-mapped workstations, and personal computers with higher-resolution graphics cards, rarely cause legibility problems.

Stand-atone hypertext has the advantage of being simple and safe: it does not increase the complexity or risk of system software, because it is not connected directly to it.

A disadvantage of stand-alone hypertext is that it is not automatically context-sensitive. On a multitasking operating system, it can be made context-sensitive by issuing a message from the (docu­mented) system to the hypertext mechanism, naming the entry point (for example, 'file names' or 'data display').

Reliable proprietary hypertext packages are available on many processors; alternatively, simple hypertext mechanisms can be implemented by means of a database, a specialised tool, or if necessary a programming language.

76 ESA PSS-05-05 Issue 1 (May 1992) THE SOFTWARE USER MANUAL

CONTENT

The recommended table of contents for a SUM is given below. If it is felt necessary to depart from this structure, implementers should justify any differences briefly, and if possible preserve the standard section numbering for easy reference.

Service Information:

a- Abstract

b - Table of Contents

с - Document Status Sheet

d - Document Change Records made since last issue.

1 INTRODUCTION

1.1 Intended readership

1.2 Applicability statement

1.3 Purpose

1.4 How to use this document

1.5 Related documents (including applicable documents)

1.6 Conventions

1.7 Problem reporting instructions

2 [OVERVIEW SECTION]

(The section ought to give the user a general understanding of what parts of software provide the capabilities needed)

3 [INSTRUCTION SECTION] (For each operation, provide...

(a) Functional description

(b) Cautions and warnings

(c) Procedures, including,

- Set-up and initialisation

- Input operations

- What results to expect

(d) Probable errors and possible causes)

ESAPSS-05-05 Issue 1 (May 1992) 77 THE SOFTWARE USER MANUAL

4 [REFERENCE SECTION]

(Describe each operation, including:

(a) Functional description

(b) Cautions and warnings

(c) Formal description, including as appropriate:

- required parameters

- optional parameters

- default options

- order and syntax

(d) Examples

(e) Possible error messages and causes

(f) Cross references to other operations)

Appendix A Error messages and recovery procedures

Appendix В Glossary

Appendix С Index (for manuals of 40 pages or more)

In the instruction section of the SUM, material is ordered according to the learning path, with the simplest, most necessary operations appearing first and more advanced, complicated operations appearing later. The size of this section depends on the intended readership. Some users may understand the software after a few examples (and can switch to using the reference section) while other users may require many worked examples.

The reference section of the SUM presents the basic operations, ordered for easy reference (e.g. alphabetically). Reference document­ation should be more formal, rigorous and exhaustive than the instructional section. For example a command may be described in the instruction section in concrete terms, with a specific worked example. The description in the reference section should describe all the parameters, qualifiers and keywords, with several examples.

The overview, instruction, and reference sections should be given appropriate names by the SUM authors. For example, an orbit modelling system might have sections separately bound and titled:

• Orbit Modelling System Overview;

• Orbit Modelling System Tutorial:

• Orbit Modelling System Reference Manual.

78 ESA PSS-05-05 Issue 1 (May 1992) THE SOFTWARE USER MANUAL

At lower levels within the SUM, authors are free to define a structure suited to the readership and subject matter. Particular attention should be paid to:

• ordering subjects (e.g. commands, procedures):

• providing visual aids.

'Alphabetical' ordering of subjects acts as a built-in index and speeds access. It has the disadvantage of separating related items, such as INSERT' and 'RETRIEVE'. Imptementers should consider which method of structuring is most appropriate to an individual document. Where a body of information can be accessed in several ways, it should be indexed and cross-referenced to facilitate the major access methods.

Another possible method is 'procedural' or 'step-by-step' ordering, in which subjects are described in the order the user will execute them. This style is appropriate for the instruction section.

Visual aids in the form of diagrams, graphs, charts, tables, screen dumps and photographs should be given wherever they materially assist the user. These may illustrate the software or hardware, procedures to be followed by the user, data, or the structure of the SUM itself.

Implementers may also include illustrations for other purposes. For example, instructional material may contain cartoons to facilitate understanding or to maintain interest.

Icons may be used to mark differing types of section, such as definitions and procedures. All icons should be explained at the start of the SUM.

Date: 2016-01-03; view: 678