User Guide

Download 68.08 Kb.
NameUser Guide
A typeUser > manual > User

Template for IDA Project (Project Id)

Template for specific development (Contract ID)

User Guide

Issue 1

0 Preface – please read first 1

0.1 Purpose of this document 1

0.2 Use of this document 1

0.3 Function of User Guide 2

0.4 Production of User Guide 2

0.5 Forms of User Guide 2

0.6 Related documents 3

1 Introduction 4

1.1 Intended Readership 4

1.2 Applicability Statement 4

1.3 Purpose 4

1.4 How to Use this Document 4

1.5 Related Documents 4

1.6 Conventions 5

1.7 Problem Reporting Instructions 5

2 Overview 6

3 Instructions 7

4 Reference Section 9

A. Error Messages and Recovery Procedures 10

B. Glossary 11

C. Index 12

Document Control 13

Document Signoff 13

Document Change Record 13

0 Preface – please read first

0.1 Purpose of this document

  1. This document is a generic User Guide document for use by IDA projects. It provides guidance and template material which is intended to assist the relevant management or technical staff, whether client or supplier, in producing a project specific User Guide document. It is also useful background reading for anyone involved in developing or monitoring the IDA Management System (IDA MS).

0.2 Use of this document

  1. This Preface is addressed to the users of this generic document and is not meant to be retained in any project specific User Guide documents based on it.

  2. The remaining sections (numbered 1, 2, 3,…) constitute a template that should be used to construct the project-specific User Guide document.

  • Text in normal case is in the most part “boilerplate” that can be retained, amended or deleted in the document.

  • Text in italics provides instructions on how to complete a section and should be removed once the section is written.

  1. The template should be used pragmatically, that is - where a section is not relevant it should be omitted. Conversely, the material contained in this document is not necessarily exhaustive; if there is a subject that is relevant to the project, but is not included in this document, it should still be included.

  2. This document has been prepared using MS Word 97. The following variables are currently recorded as File “Properties” under MS Word. They may be modified by that means or overwritten directly at each occurrence in the document, at the discretion of the user.

a. “Summary” Properties


Type of document (i.e. User Guide)


Author(s) of document


Document reference (i.e. IDA-MS-UG)

b. “Custom” Properties

Proj Id

Short mnemonic of IDA Project (set, in this document, to “Project Id”)


Full name of IDA Project (set, in this document, to “Template for IDA Project”)

Contr Id

Short identifier of contract (set, in this document, to “Contract ID”)


Full name of contract (set, in this document, to “Template for specific development”)


Issue number (currently Issue 1)


Date of document (currently 17 January 2001)

0.3 Function of User Guide

  1. A User Guide is a document designed to help users and potential users of a system. But there are many possible variants within that. A User Guide may be

  • a guide to the whole system or to a component package

  • written before or after development

  • designed primarily for training or for reference purposes

  • intended for use by a designated type of user (See 1.1).

0.4 Production of User Guide

  1. In general, there should be one overall User Guide for each IDA Project. There may also be subsidiary User Guides for specific parts of the system or for specific classes of user.

  2. There may also be separate User Guides for bought in software packages used within an IDA Project, but provision of appropriate “Help” files for each package will usually make such documents unnecessary.

  3. The User Guide(s) should be written in the context of an “operation and support plan” or somesuch, which should be included in the Global Implementation Plan. This should cover such issues as:

  • how much training will be given? how?

  • how self-sufficient are users expected to become?

  • how embodied in broader business processes will use of the system become?

  • how much support will there be?

  1. It is recommended that a complete outline User Guide be drafted prior to any development within an IDA Project, as a companion to the User Requirement document

  • as evidence that the specification in the User Requirement document are consistent and coherent

  • to give the user community a clear indication of what they can expect to be getting

  • to provide the developers with a useful view of their target, and a reminder of the need to assess specification changes from the user perspective.

0.5 Forms of User Guide

  1. Give some thought to the form of presentation of the User Guide. What form will offer the users an appropriate level of utility and convenience without incurring excessive costs for production, distribution and maintenance? Will it be A4, portrait, single-sided, and unbound? Will it be A5, landscape, double sided, wire bound? Or what?

  2. Avoid having User Guides which are subject to loose leaf updating. These are always very expensive to maintain (unless user time is of zero value) and they are always very unreliable and therefore of limited utility.

  3. Note that the paper element of a User Guide might be very small. The main part should be available on line, in accordance with modern practices, and particularly the thrust of IDA, which is to move away from paper. The User Guide may therefore be primarily embedded in a set of HTML pages or a Help file.

  4. There should also be provision for an active User Guide – one which answers the question “How Do I?” with a Wizard that helps.

  5. Consider the desirability, in certain circumstances, even where the bulk of the User Guide is available on line, of developing a “quick reference” guide, e.g. the folded sheet of A4 which is stuck to the side of the monitor with blue tack.

0.6 Related documents

  1. The document “IDA Lifecycles” presents an overview of the documentation of the IDA Programme and of the IDA Projects and development contracts executed under its auspices.

  2. Within that, the following documents are specifically related to the User Guide document.

a. For the IDA Project

Project Definition document

Global Implementation Plan

User Requirement document

b. For a development contract within an IDA Project

System Requirement document

The remainder of this document comprises a skeleton of a User Guide document. Throughout there are embedded instructions and guidelines in italics, as in this paragraph. All such material should be omitted from the User Guide document itself, as should the whole of this Preface.


1.1Intended Readership

  1. Define the categories of user to whom the User Guide is addressed. Note that these may be, for example, e.g.

  • end users

                  1. specialists, accessing the system for a significant proportion of their time, possibly for specific types of operational function

                  2. casual” users making occasional use of the system

  • various types of system operator, including

                  1. data entry staff

                  2. system adminstrators, concerned e.g. with system installation, user registration, system accounting, data administration, security, performance

                  3. user support staff (“Help Desk”).

  1. For each identified category of users:

  • define the level of experience assumed

  • state which sections of the User Guide are most relevant to their needs.

  1. Consideration should be given to the users being non-native English speakers.

1.2Applicability Statement

  1. Define the software release(s) that this issue of the User Guide applies to.


  1. Define both the purpose of the system and the purpose of the User Guide.

  2. Name the process to be supported by the system and the role of the User Guide in supporting that process.

1.4How to Use this Document

  1. Describe what each section of the document contains, its intended use, and the relationship between sections.

1.5Related Documents

  1. List all the documents referred to in this document







  1. Summarise symbols, stylistic conventions and command syntax conventions used in this document.

  2. Examples of stylistic conventions are bold type and Courier font to distinguish user input. Examples of syntax conventions are the rules for combining commands, keywords and parameters.

1.7Problem Reporting Instructions

  1. Summarise the procedure for reporting software problems.


  1. This section should provide a broad description of the system and should give the user a general understanding of its capabilities and how they are invoked.

  2. The system should be described primarily from an external ‘black box’ point of view, i.e. the discussion should be concerned with functions, input and outputs that the user will see. However, where it helps explain to the users what the system does, the black box view can be partially elaborated with an explanation of what parts of the system provide the capabilities specified.1

  3. This section may also include assumptions on the level of expertise required, e.g. use of a browser for web-based applications, picking a value from a drop-down list.


  1. This section should aim to give new users an understanding of how to operate the system.

  2. 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

  1. Care should be taken to present these operating instructions in a manner and structure suited to the needs of the users rather than according to the perspective of the development staff. The purpose of the User Guide is to help the user use the system effectively, safely and congenially, rather than to help the user understand the technicalities of how the system is constructed.

  2. For end users in particular this entails organising the User Guide in accordance with the processes and functions of the application, i.e. of the overall system of activity in which the user participates and to which the telematics system provides support.

  3. Specialist end users, who may be expected to accessing the system for a significant proportion of their time, may be deemed to require a training course before using the system. In that case the User Guide may be conceived more as a training manual than as an operational reference book.

  4. A User Guide on paper is less likely to be useful to “casual” users who make only occasional use of the system. Experience says that such users will rarely consult a manual. So for them the bulk of the User Guide information has to be available on line, supported by a good indexing system and (ideally) some diagnostic wizards. And the need for even that should be minimised by making system operation as simple, normal, intuitive, and forgiving, as possible.

  5. For all types of user there is a potential need for instructions (possibly different for different types and classes of users) concerning such things as how to

  • initiate a session of usage

  • register as a new user

  • change a password

  • diagnose a problem

  • obtain help

  • report a fault

  • terminate a session.

  1. Users who are not “end” users, directly concerned with the application itself, but rather concerned with the operation and support of the system, require their own forms of operating instructions. These may be in separate sections of a common User Guide or in separate documents.

  2. Topics to be addressed might include, for example, any or all of the following.
a.user administration and support

            1. registration of users

            2. assignment of capabilities (usage permissions)

            3. user supervision and Help Desk functions administration

            1. password administration

            2. data sensitivity control

            3. data encryption

            4. authentication of users and equipment

            5. protection against viruses and other malevolent agents administration

            1. set up and maintenance of system data

            2. storage space allocation and management

            3. data back up and recovery

            4. verification of data integrity

            5. correction of data corruption
d.usage and performance

            1. collecting and reporting on measures of system behaviour and performance

            2. system usage accounting and charging

            3. performance tuning
e.control of system operation, including

            1. starting and stopping

            2. allocation of resources, adjudication on conflicts

            3. monitoring of activity levels
f.operational control of telecommunications, including

            1. establishment and verification of links to new players

            2. supervision and control of network operation

            3. diagnosis of telecommunications malfunctions

            4. telecommunications status reporting
g.system management

            1. system installation

            2. verifying the correctness of system operation

            3. diagnosis of system faults

            4. configuration control

            5. change control

            6. registration and management of reports of system malfunction.

4Reference Section

  1. This section should give comprehensive information about all the system capabilities.

  2. 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
e.Possible error messages and causes
f.Cross references to other operations

  1. Where all the details which this section would contain are included in comprehensive on line “Help” files, the distributed version of the User Guide document may omit this section, and include just a reference to the “Help” files. However, it may even then be found preferable to include all details in the User Guide document, at least while the system is under development.

A. Error Messages and Recovery Procedures

  1. This section should list all the error messages. It should not simply repeat the error message, but should also give a diagnosis and suggest recovery procedures.

  2. If recovery action is likely to involve loss of inputs or loss of stored data, the user should be reminded about backup and archiving procedures.

  3. Where all the details which this section would contain are included in comprehensive on line “Help” files, the distributed version of the User Guide document may omit this section, and include just a reference to the “Help” files. However, it may even then be found preferable to include all details in the User Guide document, at least while the system is under development.

B. Glossary

  1. A glossary should be provided if the manual contains terms that users cannot be assumed to know, or that are ambiguous.

  2. Optionally, at the discretion of the developers, the Glossary may be merged with the Index below, giving the reader a combined a statement of

  • what the terms mean

  • where in the document they are used (including perhaps where they are defined in more detail).

C. Index

for manuals of 40 pages or more

Document Control


User Guide


Issue 1


17 January 2001


John Brinkworth, Bill Waghorn


Project Sponsor
Project Team






Reissue as complete document only

Document Signoff

Nature of Signoff






John Brinkworth, Bill Waghorn

Project Manager, Consultant


Mark Pillatt


Document Change Record




Change Details

19 December 2000

Issue 1 Draft D

John Brinkworth, Bill Waghorn

First issue for review

04 January 2001

Issue 1 Draft E

Mark Pillatt


10 January 2001

Issue 1 Draft 6

Sue Turner

Corrected formatting

17 January 2001

Issue 1

Mark Pillatt

Apply review comments and issue

1 Indeed, it is sometimes expedient, as an aid to comprehension, to describe a structure which is materially different from but functionally equivalent to that of the real system.

Share in:


User Guide iconUser Guide/Installation Guide/api documentation/sdk developer Guide/Training Materials

User Guide iconUser Guide lrp quadra Pro 2 Charger User Guide

User Guide iconUser/Admin Guide, api guide, and other documentation for online tech support application

User Guide iconPlease Note This user guide is intended to assist users specifically...

User Guide iconUser Guide

User Guide iconUser Guide

User Guide iconUser's Guide

User Guide iconUser’s guide

User Guide iconUser’s Guide

User Guide iconUser Guide

User Guide iconUser Guide

User Guide iconUser’s Guide

User Guide iconUser Guide

User Guide iconUser Guide

User Guide iconUser Guide

User Guide iconUser’s Guide 3

User Guide iconUser's guide

User Guide iconUser Guide for the

User Guide iconUser’s Guide

User Guide iconUser Guide


When copying material provide a link © 2017