Defining User Manuals

White paper prepared by Codel Services Ltd ©

Introduction

Purpose of this document

This document sets out an approach to completing the user manuals using the process design document as a reference point.

Objectives of the user manual document

This document has 5 main objectives:

	Toolset guidance: To describe how the tools available at handover are to be used to complete the steps in the procedure.
	Business guidance: To give guidance, by the way of checklists, as the best way to interpret results from reports, to complete analysis tasks and how to apply business rules to the activity at hand.
	Exception resolution: To list the correct remediative action for a range of both business and technical exceptions that can be identified during the course of the sub-process
	Governance description: To list names of representatives involved in the sub-process, their function, and how the organisation and teams are to be structured to complete the tasks
	Auditable deliverable: To satisfy an audit requirement to document the steps that will be followed, and to ensure that the steps themselves follow an evidence-based approach that can itself be audited.

These aims are achieved in three key complementary sections to this document:

	Context: This re-iterates the purpose of the sub-process, and then gives a description of the governance structure of business functions that will partake in this sub-process. Finally names of individuals and their contact details are shown.
	Scenarios: These are taken from the work instructions documents and set out the procedures the participants must follow in a number of different cases. These cross reference to the following “how to” section
	How-to description: Step by step descriptions, with extensive use of screen shots to show users how to complete the tasks set out in the scenarios. This covers not only usage of technical resources, but checklists as how best to complete a business task.

Scenario approach

The main aim of a process design documents (usually at a sub-process level) is to describe in detail, how to produce a set of deliverables in the most effective manner.

Typically there is not one “correct” path in which to produce these deliverables, as there could be differences in the steps to cover situations where exceptions occur and differences in how to react to information that comes from different sources.

Describing this in words (a requirement of the work instruction) in one hit would be hard to follow, so instead a number of scenarios are defined for each sub-process, each describing a specific and stated case.

Relation to process design deliverables

There is considerable overlap between this user-guide and the process design. This is deliberate and ensures complete coverage from a how to perspective, against the process design.

The differences are mainly on emphasis – the process design documents are focussed on design, so take a generic view on resources and how steps are to be executed. In the User Manual, sufficient detail is required in order for the reader to be able to actually perform these tasks.

Key points of overlap are the:

	Resources: The tables on roles and responsibility are identical, however in the user manual document actual names and their contact details are included, since in order to complete many of these tasks details of who the person responsible for it is required.
	Scenarios: The procedural steps in both are identical. However in the user guide these are cross references to the “How-to” section
	Business Artefacts: The range of business artefacts described in the Supplementary specification of the work instruction is the same. However in the User Manual these are expanded in the “How-to” section, showing how the artefact is initiated, recorded, analysed etc.

In summary, the advantage of using the process design as the basis for the user manual is Completeness and consistency.

This paper has been prepared by Codel Services Ltd to illustrate how structured business modelling can help your organisation. Codel Services Ltd is an IT Consultancy specialising in business modelling. If you would like further information, please contact us at: Deryck Brailsford, Codel Services Ltd, Dale Hill Cottage, Kirby-Le-Soken, Essex CO13 0EN,United Kingdom. Telephone: +44 (0)1255 862354/Mobile: + 44 (0)7710 435227/e-mail: info@codel-services.com