Writing the Manuals
Home Business Change Analysis & Design Agile Testing Templates About us


Writing the user manual: Suggested approach

By taking the following a formulaic approach to writing the user manual, their delivery can be simply a case of reviewing the process design documents and then filling in the blanks.

Care however should be taken not to simply republish the process design document under the guise of a user manual. These are two separate deliverables.

It is thus recommended that the following approach be used.

1. Each user manual needs to be written from a single user’s perspective

bulletTheir purpose is not to evaluate or analyse the end to end process or understand handovers
bulletTheir purpose however is to give the user instructions how to do their job with the tools at their disposal

2. Evaluate the scenarios in the process design document and ask “how does the user fulfil this step”

For each step ask:

bulletWhat are the objectives of this step specifically to the end user
bulletWhat actions a user will actually performs to perform the step
bulletWhat domain expertise a user will need to apply to business domain objects referenced by the step (e.g. business rules or reports)

3. Provide explanatory detail to the above.

This explanatory detail is typically one of either (or both):

bulletScreenshot walkthrough using the available technology that a user must follow. This largely covers the to meet the scenario steps required by the process design
bulletGuidance notes to reinforce the usage of the technology. This largely covers the static elements of the process design document such as validation, formatting and other business rules, how an output is used to support the flow (e.g. how to analyse a particular report to make decisions required by the process flow)

4. Wherever possible seek direct input from the end users (or a representative) in writing these documents.

The users are best placed to evaluate whether the prose is written in a style best suited to the company’s environment and culture.

bulletAim to get end-users to drive the template or look-and-feel of the user manual to a format they are most comfortable with
bulletBy gaining end user involvement in their creation, will greatly facilitate later training

5. Rationalise the document to make it readable for the audience in mind.

Remember that this is not an analysis document, rather a document that may be referenced on a daily basis. For example:

bulletAreas of commonality (e.g. logging on) can be described in one section and referenced elsewhere,
bulletScenarios may also be consolidated to better reflect key stages of the user’s daily experience, focussing less on branches of logic, but rather telling a complete and coherent “story”
bulletThus the user manual is broken down into a series of section headings, each supported by a description of the objectives of that stage of the process to the user, with either a screen-shot walkthrough (with explanatory text), and/or guidance notes to support.

Back Next

© 2002-2007 Codel Services Ltd

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