Unit Create technical documentation

Information
LO 1:- Identify and analyze documentation needs
sheet
Why user documentation is so important?

Computer users need documentation so that they can make the best use of their computers as
work tools. A computer system can assist them to do their work efficiently and effectively but
they need to be able to do three things:
 learn how to use the system and its applications
 know how to get help when they need to learn more
 know what to do when they experience problems.
Users will be working across all parts and levels of an organisation carrying out different
functions such as data entry, financial administration, executive and middle management.
However, user documentation is for anyone in an organisation who needs assistance with these
three tasks.
Types of user documentation
Users might need to consult a range of documentation in order to install, configure and/or use the
functions of a system or application. There are many different types of user documentation
depending on what users require. For example, a new staff member using a particular IT system
for the first time needs to refer to a user guide and tutorials and online help. In other words, they
firstly need documentation that helps them learn to use the software. As they become more
familiar with the system, they will need access to other types of documentation such as FAQs
(Frequently Asked Questions).

Think of the types of user documentation you have seen at a workplace. Do some of your
examples include the following?
Documentation type Description

Project specifications specifies the detailed business requirements of the project

including how the system will work and the underlying
functionality
Reports produced by the system, program, network or application
Help resources provides online Help, quick reference cards, scenarios,
FAQs (Frequently Asked Questions). Users can search for
help on using of a specific system, program, network or
application
User manual/guide describes how the user will use a system, program,
network or application to do their job

Prepared by Salik Akmel

Page 1
 Training materials
Self-paced tutorials
Brochures
train staff in how to use a system, program, network or
application to do their job
teach staff how to use a system, program, network or
application to do their job. These may be online or paper-
based tutorials.
outline what a computer application does

The purpose of user documentation

What is the documentation going to be used for? This is the first question to ask before starting
to create any user documentation. When you are satisfied that you have an answer, you can then
decide what type of documentation you are going to produce.

Reflect
Think about documentation you have used and recall why you needed to refer to it. What was the
main purpose of the documentation? What did it enable you to do? These are some examples of
user documentation and their purpose.
Examples Purpose

A project specification, training to learn how to use a piece of software

manual, user guide, tutorials or help
that provides step by step guidance
in how to use the software.
A training manual, quick reference to refer to a specific feature of a piece of software
guide or user guide that provides
detailed commands and
specifications of a software package
to assist with troubleshooting
problems.
Once you have decided what the purpose of your documentation is and what type of documentation you are
going to produce, you can look at the needs of the potential users of the documentation

User need analysis

A needs analysis is a process where the needs of the target groups for the documentation are
identified and analysed. This analysis helps to make decisions on what the documentation should
contain and what format is most suitable. For example, Data Entry staff in a call centre need to
know how to correctly enter data in a database so that orders can be generated correctly from a
database.
For training materials and online help a needs analysis should be conducted in person with the
staff who will need the documentation. For other documentation a look at the needs of the users
without speaking directly to staff is sufficient.
Prepared by Salik Akmel
Page 2
After considering user characteristics and needs, possible solutions can be found, for example:
User characteristic
level of computing experience
experience with the particular
system or application
frequency of use with a
particular system or
application
workplace tasks
work practices and
environment
language skills
cultural background
personal characteristics such
as aptitude, educational
background, age, disability
level of confidence
It’s almost impossible to cater for all these variations. However in preparing documentation for a
new user, you would obviously not confuse them with technical jargon on the first page! You
Prepared by Salik Akmel
User need
beginner to expert
beginner to expert
constant, frequent to weekly,
monthly, annually
simple, repetitive tasks to complex
tasks
eg part-time, shift work, office,
warehouse
difficulty reading and
understanding written language to
very competent readers
language appropriate to some
users may not be appropriate for
others
users will learn at varying pace
users might be fearful and not
confident with computers
Page 3
Possible solutions
create different sections for
different levels of experience
create different sections for
different levels of experience
there must be initial training with
some sort of follow-up support
documentation must clearly
relate to the tasks at hand
occupational health and safety
documentation is essential
 keep language simple, use
plain English
 explain technical terms and
jargon if they must be used
 avoid long uncommon words
if simple words will do
 use language appropriate for
all users
 American spelling often
appears in documentation,
since it is often where the
software originates
make sure individual needs are
catered for to organisational
policies
 be positive and encouraging
in your approach
 avoid reinforcing negative
attitudes
 need to find a balance and remember that any documentation must be consistent with the
organisation’s policy, conventions and standards.
For any form of documentation to be useful it must be designed with the needs of its potential
users in mind. An analysis of the requirements of the users, and the way their needs can be
effectively addressed, is a critical step in the process of determining documentation
requirements. \

Unit Create Technical Documentation

Information
LO 2:-
sheet Design documentation

It’s a good idea at this stage to think about the content that you will include in the user
documentation. This is so you can estimate the number of pages, the complexity of the content
and what the graphic and text components will be.
The content will have some influence on:
 design of the documentation, including layout, use of text and graphics
 medium, eg paper-based or online
the time and resources needed to develop the documentation

media for user documentation

You can consider paper-based documentation, online documentation or a combination of both.

The media type you choose will be influenced by the:
1 purpose of the documentation
2 user needs and characteristics
3 content (subject matter).
Always keep in mind that you need to include a range of items that allow users to access the
required information quickly and easily. There are advantages and disadvantages to online and
paper media. \

Prepared by Salik Akmel

Page 4
 Media Advantages Disadvantages

Paper  conventional, most people are  hard to maintain

used to paper products control of different
 easy and fast to prepare versions
 inexpensive to produce  costly to update
 requires readily available
software
Online  convenient  can be expensive
 easy to reach many people  requires specialised
geographically dispersed software
 can be colourful and fun
 can link to other related
documents
 easy to maintain version
control
 not costly to update

Reflect
Think about when you would be most likely to use paper and when you would use online.
Paper is appropriate in most circumstances. It is the most commonly used method of delivering
documentation, so most people are used to it and like it. However, when staff are dispersed
across a country or around the world, online delivery is best. Everyone can access the same
documentation and only one version is available. Where user documentation is going to be used
primarily as a help tool, then online help is most appropriate. It allows for easy searching across
the documentation.
Designin a template
Once you have determined the documentation requirements, you can develop a template that
meets those requirements and makes the job easier. A template is a file that contains a standard
layout, styles and fonts that are used in the production of the documentation.
When you want to create a file for user documentation, you open the standard template, usually
in Word, and the layout, fonts and styles are already set up in the document. All you need to do
is start writing. Everyone uses the same template, so there is a consistent look and feel to all of
the user documentation.
The template may be:
 a Word template
 an HTML template
 an online help template.
The medium will determine what kind of template you use.

Prepared by Salik Akmel

Page 5
 Features of templates

Paper-based documentation

Features that may be included in paper-based documentation are:

 table of contents

 columns and tables

 page and section numbering

 headers and footers

 graphics and text surrounds

 substantially chunked information

Online documentation

Features that may be included in online documentation are:

 table of contents hyperlinks

 tables

 links to other pages/sites

 navigation icons

 usability/functionality

 heavy use of graphics.

Prepared by Salik Akmel

Page 6
 Unit Create Technical Documentation
Information
LO 3:-
sheet Develop 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.

Prepared by Salik Akmel

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

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.

Prepared by Salik Akmel

Page 8
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.

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.

Prepared by Salik Akmel

Page 9
 Unit Create Technical Documentation
Information
LO 4:-
sheet Evaluate and edit documentation

Assume you have completed the first draft of your user documentation and feel a great sense of
achievement. Now it is time to put your work out there for the users to evaluate.

Who reviews the user documentation?

The process for the review of the user documentation is generally outlined in the organisation’s
user documentation policy. If you are working on a specific project, the project manager may
have an approach that they prefer you to use.

Generally, documentation is reviewed by:

1 the designated project team members who have knowledge of the system, program, network
and/or application

2 a subject matter expert.

What is the review process?

The review process varies from organisation to organisation and project to project. The review
process is generally outlined in the organisation’s policy or the project documents. It may be
called something like ‘change control’. A basic process is shown in the following table

Prepared by Salik Akmel

Page 10
Table 1: Review process

Person Role

Technical writer The Technical writer creates the user documentation.

Project team members
Subject matter expert (SME)
Business unit stakeholders
They then manage the process of obtaining feedback from
the project team, SME and key stakeholders and changing
the documentation to meet their needs. The
documentation is then handed to the Project Manager
once final sign off is obtained.
Generally, a small group of members of the project team
will be designated to perform an initial review the
documentation. If changes are required, the document
will be returned to the Technical writer and the review
process will start again.
The documentation will then go to a subject matter expert
or a group of subject matter experts for review. If changes
are required, the document will be returned to the
Technical writer and the review process will start again.
The business unit stakeholders are generally senior
management who have a stake in the system, program,
network and/or application you are writing the
documentation for. These people are generally listed on
the Project Brief, depending on the organisational policy.

What do the reviewers review?

Reviewers tend to concentrate on the content. They evaluate whether it is correct and complete.
Some reviewers will also give feedback on the spelling, grammar and presentation and how they
think a document should be improved.

Analysing the feedback

When the feedback is received the Technical writer will need to determine if the feedback is
valid. If there are doubts, he or she will get clarification from the person requesting the change
until the reason for the change is clear. Generally, changes that are requested by the reviewers
are made.

Prepared by Salik Akmel

Page 11
 Version control
When writing documentation of any kind, it is a good idea to have version control process in
place to ensure that changes are not lost and versions are not confused. This will often be
outlined in the user documentation policy.
You may have a personal system that you prefer or may like to use a standard system.
Either way, it is critical to establish how you are going to name and number the various versions
of your documents and to communicate that process to other writers and reviewers so that
everyone is on the same page.
For example, the first draft of a user guide is called ug_draft0.1. After 2 reviews and changes it
becomes ug_draft0.3. When the document has completed its final review and has been signed
off, it becomes ug_version 1.

Documentation sign off

Once the documentation has been reviewed and all of the reviewers are happy with it, you can
send it to the relevant people for sign off.

Who signs off?

The project brief or other document that initiates the system, program, network and/or
application development or upgrade will generally list the project and business unit stakeholders
who are responsible for sign off on all of the deliverables, including documentation.
These people will include the:
 project owner
 business unit managers where the system, program, network or application is being
implemented
 project manager
 other key stakeholders in support roles such as trainers, human resource officers and
change managers.

The sign off process

This process involves passing the reviewed documentation to each of the key stakeholders who
have the responsibility for signing-off on the documentation.
Generally, there will not be any further changes requested as the key stakeholders will rely on
the reviewers to identify any necessary changes. However, if further changes are requested by
the key stakeholders, the changes are made and the review and sign off process starts again.

Prepared by Salik Akmel

Page 12