Produce user documentation

Types of user documentation 2

Reviewing the system, program, network or application 4

Using a user’s perspective 4
Gathering existing documentation 4

Writing effective user documentation 5

Planning content 5
Tips for writing and designing effective user documentation 6
Involving business units in the development of user
documentation 7

Developer tools 8

Quality assurance (QA) 9

QA checklist 9
Usability testing 11

Summary 12
Check your progress 12

TTLM: Produce user documentation 1

2005
Bako, Ethiopia
Types of user documentation

When a new computer application is implemented or changes are made to

existing computer applications, documentation that explains how the
computer application works may need to be provided directly to users
and/or to the help desk.

There are different types of documentation that can be available for each
computer application, for example:
1 user manual/guide
2 technical manual/guide
3 training manual/resources.

When software is purchased off-the-shelf it usually comes with a user

guide and technical guide. Training resources are then either purchased or
developed in-house.

When computer applications are developed internally, a user guide,

technical guide and training resources are usually developed to support the
application. If the development is outsourced then the same supporting
materials are usually developed as part of the project. Outsourcing occurs
when external staff are hired to develop the computer application.

So, client documentation for software applications is generally prepared by

the people/organisation who design and develop the application.

A user guide shows the user:

 how to use the application, ie the steps required to complete various
tasks
 screens dumps with ‘dummy’ data to give the user a complete picture
of how to enter data and process the data
 tutorials.

Note that this guide can incorporate a training resource such as a tutorial.

The technical manual generally contains the technical information such as:
 system requirements to run the application
 how to install the application
 configuring the application

2
  database layout (if a database is used)
 screen layouts
 how to get technical support.

At the end of any project to develop a computer application, a copy of all

documentation should be provided to:
1 the client
2 the help desk.

The help desk can then provide support to users when they contact them for
support.

Providing support to clients for macros/templates

Just like computer applications, macros and templates need to be supported
by the help desk. When new templates have been developed or new macros
set up in standard software packages, copies of the templates and lists of
macro codes and purpose should be sent to the help desk.

When staff members contact the help desk because a template is being
troublesome or a macro is not working, they can consult these documents to
assist the staff member.

TTLM: Produce user documentation 3

2005
Bako, Ethiopia
Reviewing the system, program,
network or application

Before you can start writing documentation, you need to know how the
system, program, network and/or application that you are documenting
works.

Using a user’s perspective

The only way to find out how the system, program, network or application
works is to become a user so that you become familiar with its features and
you are confident in using it.

You should be looking at:

 the functionality — how it works
 the work processes surrounding its use — how the system works with
organisational processes and procedures.

Another valuable source of information are staff members who are already
users or project team members who have been working with the system.

Gathering existing documentation

If you are writing documentation for an existing system, program, network
and/or application, some documentation may already exist. You should
consult any existing documentation that may have accompanied the system
(including technical information). This could include:
 user guides
 project specifications
 online help
 procedure manuals.

These documents will show you how the system, program, network or
application works. It should also show you what the organisation’s work
procedures are and how to apply them.

4
Writing effective user documentation

As a confident user of the system you can begin to write the documentation
using the agreed template and relevant tools. You will need a template for
user documentation and the relevant tools for development.

Planning content
In the same way that you plan any piece of writing, you will need to create a
plan for writing the documentation. Before you write the user
documentation, write an outline of the contents. Organise the content into:
1 main headings
2 sub headings
3 points under each of the subheadings.

It might be necessary to approach a subject matter expert to assist with the

planning or it might be sufficient to use any existing documentation as a
model for the new documentation.

When writing the content, it is important to follow effective writing

principles. Other features such as graphic design and navigation will help
user documentation work for users. Along with getting the content right,
you’ll need to use sound principles for layout and usability as well.

A final stage in the development of your documentation will be testing the

documentation with real users, then revising the documentation and testing
it again. So you’ll have the opportunity to adjust content and other features
to better fit the needs of your target users.

Reflect
Think about the features that you have found useful in documentation. What
were they?

TTLM: Produce user documentation 5

2005
Bako, Ethiopia
 Tips for writing and designing effective
user documentation
Use this as a checklist for planning the features of user documentation.

Content features
 Give a brief introduction where you state the purpose and objectives of
the documentation.

 Include a table of contents or index.

 When writing, keep the users’ needs in mind, ie put yourself in the
users’ place.

 Ensure the content is accurate.

 Make clear sections for different types of features/information.

 Break the content down into easy-to-digest ‘chunks’, eg using

paragraphs and sub headings, or multiple screens.

 Use illustrations, diagrams, charts and/or screen shots where

appropriate.

 State instructions clearly and step-by-step.

 Use plain English and avoid jargon.

 Use technical terms only where necessary.

 Include a troubleshooting or help section.

 Include a glossary of the technical terms you have used.

Layout features
 Make the document structure as simple as possible and logical by
providing cues to locate information.

 Ensure good usability, especially for online documentation.

 Cross-reference information, eg use hyperlinks in online

documentation.

 Warnings, comments and help should be well-organised and visible.

 Aim for a clean design for text styles and layout that is consistent across
all pages.

6
 Involving business units in the
development of user documentation
One of the reasons a project could fail is that people in the business units
who will be impacted by the project’s implementation have been left out of
the consultation process. From the beginning to end of a project, project
team members need to work closely with users. They are an invaluable
resource for developing documentation.

Though users and subject matter experts from the business units might not
have the skills necessary to write effective documentation, they have the
content knowledge. If you can tap into this knowledge your content will be
accurate and relevant.

Reflect
What do you think may be the benefits of involving users and accepting
their feedback?
 The end product is more closely aligned with the needs of the users.
 The process of creating user documentation is much simpler due to the
expert knowledge users bring.
 Implementation and take-up of the new system, program, network or
application is much greater with user involvement, as the subject matter
experts can act as ‘champions’ within the business units.

TTLM: Produce user documentation 7

2005
Bako, Ethiopia
Developer tools

The writing tools you use will be determined by the medium — paper-based
or online. Tools (software) can include applications for:
 word processing
 image editing
 image conversion (to web-ready)
 painting and drawing
 HTML conversion/authoring/editing
 FTP utility
 site management software
 multimedia or slide show authoring
 audio and video equipment and editing software.

If you are developing paper-based materials, useful tools are:

 word processing software, eg Microsoft Word
 imaging software, eg Adobe Photoshop and/or Adobe Illustrator.

If your materials are going online, useful tools are:

 HTML conversion/authoring/editing
 imaging software, eg Adobe Photoshop or Fireworks
 FTP utility, eg FTP Pro or CuteFTP.

8
Quality assurance (QA)

Once the documentation has been written, a quality assurance check should
be conducted before the draft is sent out for review. This check is best done
by a subject matter expert, another member of the project team or a different
writer.

QA checklist
A standard checklist should be used to check the documentation. A QA
checklist contains a list of standard formats and styles that reflect the
organisation’s user documentation standards.

The purpose of the checklist is to ensure the documentation standards are

followed and that all user documentation is consistent in style and
appearance. Once the QA is complete, the documentation can be sent for a
formal review.

The following table lists some of the criteria you could include in a QA
checklist.

Table 1: QA checklist

Criteria Evidence to look for

Is the medium suitable?  consider work practices, frequency of updates

Are the purpose and  objectives stated

objectives clear?
Is the documentation suitable
for the intended audience?
Is the skill level of the user
stated?
 outcomes measurable
 achievable given the stated skill level of intended users
 plain language
 terms explained
 user-centred
 skills required to understand and perform tasks
specified

Is the content complete and  clear sections

well organised?
Is it easy to access and
 pages/screens numbered
 summaries included
 trouble shooting section included
 content matches objectives
Access points include:

TTLM: Produce user documentation 9

2005
Bako, Ethiopia
 Criteria Evidence to look for

navigate the information?

Are instructions clear?
Logical flow of information
Ease of use
Consistency in layout
Balance of text and white
space
Visual cues
Presentation
 table of contents
 well-developed index with accurate matches
 cross referencing
 hot spots (online)
 glossary
 legend to explain any symbols
 one task in one instruction
 instructions are numbered
 technical jargon avoided, explained where necessary,
and located in the glossary
 topics build on the preceding topic and increase in level
of difficulty
 users can find what they are looking for
 users understand it
 users believe it is complete and accurate
 heading styles used consistently
 consistent use of fonts, type and size for both headings
and body text
 font types limited to two or three
 consistent use of colour, paragraph styles, etc
 adequate use of white space
 information is easy to read and follow
 left justification been used
 adequate use of tables, illustrations, colour and other
visual elements
 different kinds of information are clearly identified for
easy reading eg
 heading
 main body text
 instructions for user to perform a task at the computer
 explanations of tasks
 warnings
 screen shots
 system messages
 comments to the user
 shortcuts to functions: function keys
 document looks interesting to read

10
 Usability testing
Online user documentation requires a test for usability. This means that the
interactive design and navigation should be tested to see whether the user
can easily find the information they are after.

It is preferable for usability testing to be performed by a subject matter

expert or a user (since they will be using the documentation when it is
finished). The organisation’s usability standards can be put into the QA
checklist.

TTLM: Produce user documentation 11

2005
Bako, Ethiopia
Summary

This reading has covered the knowledge and skills required to write user
documentation for a new or upgraded system, program, network or
application implementation. We began with ways of reviewing the existing
system, program, network or application. Then we looked at elements for
writing and designing effective user documentation and the range of tools
available. Documentation is completed after a quality assurance check and
usability testing which ensure that standards are met.

12