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
 | Their purpose is not to evaluate or analyse the end to end process
or understand handovers |
| Their 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:
| What are the objectives of this step specifically to the end user |
| What actions a user will actually performs to perform the step |
| What 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):
| Screenshot walkthrough using the available technology that a user
must follow. This largely covers the to meet the scenario steps required
by the process design |
| Guidance 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.
| Aim to get end-users to drive the template or look-and-feel of the
user manual to a format they are most comfortable with |
| By 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:
| Areas of commonality (e.g. logging on) can be described in one
section and referenced elsewhere, |
| Scenarios 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” |
| Thus 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. |
© 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
