SUMVTable of Contents

A table of contents is an important help and should be provided in every SUM. Short manuals may have a simple list of sections. Manuals over 40 pages should provide a fuller list, down to at least the third level of subsections (1.2.3, etc). Where the SUM is issued in several volumes, the first volume should contain a simple table of contents for the entire SUM, and each volume should contain its own table of contents.

There is no fixed style for tables of contents, but they should reference page as well as section numbers. Section headings should be quoted exactly as they appear in the body of the manual. Subsections may be indented to group them visually by containing a section.

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

A convenient style is to link the title to the page number with a leader string of dots:

1.2.3 Section Title .............................................................................. 29

Lists of figures and tables should be provided in manuals with many of them (e.g. more than twenty).

6.6.2 SUM\1 Introduction

6.6.2.1 SUM\1.1 Intended readership

This section should define the categories of user (e.g. end user and operator) and, for each category:

• define the level of experience assumed;

• state which sections of SUM are most relevant to their needs.

6.6.2.2 SUM\1.2 Applicability statement

This section should define the software releases that the issue of the SUM applies to.

6.6.2.3 SUM\1.3 Purpose

This section should define both the purpose of the SUM and the purpose of the software. It should name the process to be supported by software and the role of the SUM in supporting that process.

6.6.2.4 SUM\1.4 How to use this document

This section should describe what each section of the document contains, its intended use, and the relationship between sections.

6.6.2.5 SUM\1.5 Related documents

This section should list related documents and define the relationship of each document to the others. All document trees that the SUM belongs to should be defined in this section. If the SUM is a muttivolume set, each member of the set should be separately identified.

6.6.2.6 SUM\1.6 Conventions

This section should summarise symbols, stylistic conventions, and command syntax conventions used in the document.

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

Examples of stylistic conventions are boldface and Courier Font to distinguish user input. Examples of syntax conventions are the rules for combining commands, keywords and parameters, or how to operate a WIMP interface.

6.6.2.7 SUM\1.7 Problem Reporting Instructions

This section should summarise the procedures for reporting software problems. ESA PSS-05-0 specifies the problem reporting procedure [Ref. 1, part 2, section 3.2.3.2.2]. The SUM should not refer users to ESA PSS-05-0.

6.6.3 SUM\2 Overview Section

This section should give an overview of the software to all users and summarises:

• the process to be supported to by software;

• the fundamental principles of the process:

• what the software does to support the process:

• what the user needs to supply to the software.

The description of the process to be supported, and its fundamental principles, may be derived from the URD. It should not use software terminology.

The software should be described from an external 'black box' point of view. The discussion should be limited to functions, inputs and outputs that the user sees.

The overview can often become much clearer if a good metaphor is used for the system. Some GUIs, for example, use the 'office system' metaphor of desk, filing cabinets, folders, indexes etc. Often a metaphor will have been defined very early in the system development, to help capture the requirements. The same metaphor can be very useful in explaining the system to new users.

6.6.4 SUM\3 Instruction Section

This section should aim to teach new users how to operate the software. The viewpoint is that of the trainee.

The section should begin by taking the user through short and simple sessions. Each session should have a single purpose, such as 'to enable the user to edit a data description record'. The sessions should

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

be designed to accompany actual use of the system, and should contain explicit references to the user's actions and the system's behaviour. The trainee should derive a sense of achievement by controlling a practical session that achieves a result.

Diagrams, plans, tables, drawings, and other illustrations should be used to show what the software is doing, and to enable the novice to form a clear and accurate mental model of the system.

The tutorial may be structured in any convenient style. It is wise to divide it into sessions lasting 30-40 minutes. Longer sessions are difficult to absorb.

A session could have the goal of introducing the user to a set of 'advanced' facilities in a system. It may not be practical or desirable to present a whole session. It may be more appropriate to give a 'tutorial tour'. Even so, it is still helpful to fit all the examples into a single framework (e.g. how to store, search and retrieve).

For each session, this section should provide:

(a) Functional description

A description, of what the session is supposed to achieve, in the user's terms.

(b) Cautions and warnings

A list of precautions that may need to be taken; the user is not concerned with all possibilities at this stage, but with gaining a working understanding of some aspect of the system.

(c) Procedures

- set-up and initialisation operations

A description of how to prepare for and start the task:

- input operations

A step-by-step description what the user must do and a description of the screens or windows that the system shows in response:

- what results to expect

A description of the final results that are expected.

(d) Likely errors and possible causes

An informal description of the major errors that are possible in this task, and how to avoid them. The aim is to give the trainee user the confidence to carry on when problems arise. This section should not simply provide a list of errors, but should set them in their context.

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

6.6.5 SUM\4 Reference Section

This section should give comprehensive information about all the software capabilities. The viewpoint is that of the operator or expert user.

The section should contain a list of operations ordered for easy access. The order may be alphabetical (e.g. for command-driven systems) or correspond directly to the structure of the user interface (e.g. for menu-driven systems).

In contrast to the informal style of the instruction section, the reference section should be formal, rigorous and exhaustive.

For each operation, this section should provide:

(a) Functional description

A concise description of what the operation achieves.

(b) Cautions and warnings

A list of cautions and warnings that apply to the operation.

(c) Formal description, including as appropriate:

- required parameters

- optional parameters

- defaults

- syntax & semantics

Describe precisely what the operation does and how it is used. The means of doing this should be decided in advance. Syntax may be defined formally using the Backus-Naur Form (BNF). Semantics may be described by means of tables, diagrams, equations, or formal language.

(d) Examples

Give one or more worked examples to enable operators to understand the format at a glance. Commands should be illustrated with several short examples, giving the exact form of the most common permutations of parameters and qualifiers in full, and staling what they achieve.

(e) Possible errors and their causes

List all the errors that are possible for this operation and state what causes each one. If error numbers are used, explain what each one means.

(f) References to related operations

Give references to other operations which the operator may need to complete a task, and to logically related operations (e.g. refer to RETRIEVE and DELETE when describing the INSERT operation).

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

The operations should be described in a convenient order for quick reference: for example, alphabetically, or in functionally related groups. If the section is separately bound, then it should contain its own tables of error messages, glossary, and index; otherwise they should be provided as appendices to the body of the SUM. These appendices are described below.

6.6.6 SUM\Appendlx A - Error messages and recovery procedures

This section should list all the error messages. It should not simply repeat the error message: referral to this section means that the user requires help. For each error message the section should give a diagnosis, and suggest recovery procedures. For example:

file TEST.DOC' does not exist.

There is no file called 'TEST.DOC' in the current directory and drive. Check that you are in the correct directory to access this file.

If recovery action is likely to involve loss of data, remind the user about possible backup or archiving procedures.

6.6.7 SUM\Appendix В • Glossary

A glossary should be provided if the manual contains terms that operators are unlikely to know, or that are ambiguous.

Care should be taken to avoid redefining terms that operators usually employ in a different sense in a similar context. References may be provided to fuller definitions of terms, either in the SUM itself or in other sources.

Pairs of terms with opposite meanings, or groups of terms with associated meanings, should be cross-referenced within the glossary. Cross-references may be indicated with a highlight, such as italic type.

List any words used in other than their plain dictionary sense, and define their specialised meanings.

All the acronyms used in the SUM should be listed with brief explanations of what they mean.

6.6.8 SUM\Appendix С - Index

An index helps to make manuals easier to use. Manuals over 40 pages should have an index, containing a systematic list of topics from the user's viewpoint.

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

Indexes should contain major synonyms and variants, especially if these are well known to users but are not employed in the SUM for technical reasons. Such entries may point to primary index entries.

Index entries should point to topics in the body of the manual by:

• page number;

• section number;

• illustration number;

• primary index entry (one level of reference only).

Index entries can usefully contain auxiliary information, especially cross-references to contrasting or related terms. For example, the entry for INSERT could say 'see also DELETE'.

Indexes can provide the most help to users if attention is drawn primarily to important keywords, and to important locations in the body of the manual. This may be achieved by highlighting such entries, and by grouping minor entries under major headings. Indexes should not contain more than two levels of entry.

If a single index points to different kinds of location, such as pages and illustration numbers, these should be unambiguously distinguished, e.g.

• page 35

• figure 7

as the use of highlighting (35, 7) is not sufficient to prevent confusion in this case.

ESA PSS-05-05 Issue 1 (May 1992) 85 LIFE CYCLE MANAGEMENT ACTIVITIES

Date: 2016-01-03; view: 715