Create User
Documentation
ICAD3218A
Procedure for Creating User
Documentation



Determine documentation standards and
requirements
Produce user documentation
Review and obtain sign-off
ICAD3218A - Create User Documentation
Key Concepts and Terms














appropriate person/s
approval
blueprint
characteristics of effective user documentation
create user documentation
documentation process
documentation requirements
function and features of templates
gather and analyse feedback
general features, benefits and limitations of
paper-based and online user documentation
general features, benefits, limitations and
working knowledge of software tools/packages
identify and clarify needs of the target audience
investigation and research into the
system/platform/network/application to be
documented
naming standards












points to consider when writing content
principles of instructional, document and web
design
proof-reading and review of user documentation
purpose of user documentation
standards
storage, distribution and maintenance/ review of
user documentation
style guides
target audience
tracking processes
types of user documentation
user documentation
version control.
Types of user documentation
There are different types of documentation that can be
available for a computer application, for example:
 user manual/guide (usually comes bundled with
software)
 technical manual/guide (usually comes bundled with
software)
 training manual/resources (usually purchased
separately or developed in-house)
Types of Documentation
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
Training materials
•
train staff in how to use a system, program, network or
application to do their job
Self-paced tutorials
•
•
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
Brochures
User Guide
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.
Technical Manual
The technical manual generally contains the
technical information such as:
 system requirements to run the application
 how to install the application
 configuring the application
 database layout (if a database is used)
 screen layouts
 how to get technical support.
Purpose of documentation




providing instruction for use of hardware and
software Technologies
training resource for better use of Technologies
recording of policies and procedures in the business
reference/source of information.
Computer users need documentation so that they can make the
best use of their computers as work tools
 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.
Types of user documentation.
Documentation can be :
 paper-based, or
 Online
There are two broad audiences for documentation :
 internal (for in-house use, used by the same
company/organisation that develops it)
 external (for outside use, for users outside the
company/organisation that develops it).
What does documentation look like
Books, manuals, computer-based tutorials and online help are all
media for user documentation.
Documentation now being moved to electronic form because :
 increased productivity — users have up-to-date,
comprehensive information that they can access quickly and
easily.
 increased corporate intelligence — information is stored
centrally but distributed universally
 consistency and quality — documentation appears in the
same format and is easily updateable
 reduced printing costs.
If documentation is ineffective or not
provided
Ineffective documentation can:
 reduce efficiency – staff spend time trying to work
out how to perform tasks
 waste resources – staff can work inefficiently and
waste time or other resources
 increase costs of training – training is expensive and
it is cheaper to provide staff with documentation so
they can teach themselves
 users reject a system that they don’t understand or
find difficult to use
Why documentation fails
Documentation can fail due to :
 user attitude
 management attitude
 writer’s attitude
Failure due to user’s attitude
Users will reject documentation for various reasons
including :
 User finds it too hard to find information
 User finds documentation too difficult to understand
 The documentation contains information that is old
 User is too lazy to look
 User is turned off because manual is too thick
Failure due to Management Attitude
Documentation can fail due to the attitude of management
including
 Time constraints placed upon the user or the developer of the
document
 budget constraints placed upon the developer of the
documentation or not purchaising sufficent documentation
(eg buying only technical manuals and no training guides)
 failing to communicate with technical staff during the design
of the documentation or encourage user to use
documentation.
 not highly valued – not supporting the developer or the staff
using the documentation.
Failure due to writer’s attitude
The writer’s attitude can effect the
documentation by :
 not taking enough time to understand the
system before writing
 more concerned about the look of the
document (design factors) than content.
Effective documentation will :
Take into consideration the differences between
target audience (users)






personalities
experience
cultural background
attitudes and values
language
environment
Consider the User
User characteristic
User need
Possible solutions
•
level of computing
experience
•
beginner to expert
•
create different sections for
different levels of experience
•
experience with the
particular system or
application
•
beginner to expert
•
create different sections for
different levels of experience
•
frequency of use with a
particular system or
application
•
constant, frequent to weekly,
monthly, annually
•
there must be initial training
with some sort of follow-up
support
•
workplace tasks
•
simple, repetitive tasks to
complex tasks
•
documentation must clearly
relate to the tasks at hand
•
work practices and
environment
•
eg part-time, shift work,
office, warehouse
•
occupational health and
safety documentation is
essential
•
language skills
•
difficulty reading and
understanding written
language to very competent
readers

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


Consider the User (Continued)
User characteristic
User need
Possible solutions
•
•
language appropriate to some
users may not be appropriate
for others

cultural background

use language appropriate for
all users
American spelling often
appears in documentation,
since it is often where the
software originates
•
personal characteristics
such as aptitude,
educational background,
age, disability
•
users will learn at varying pace
•
make sure individual needs
are catered for to
organisational policies
•
level of confidence
•
users might be fearful and not
confident with computers

be positive and encouraging
in your approach
avoid reinforcing negative
attitudes

Effective documentation will :

see everything from the user’s point of view

be available in a form and place that users can
refer to when needed

Know and understand its target audience (set
of users).
Effective documentation will :
have information that is




easy to find
easy to comprehend
up-to-date, reflecting latest changes and revisions
to the system
reliable and convincing
Effective documentation will :
show the user how to



call information to the screen
manipulate the information
store the information as required
The documentation process
The Steps for creating user documentation :
 plan
 draft
 review/edit
 test
 produce
 distribute
 maintain/revise.
Points to consider when creating
documentation





user’s needs
appropriateness to task
usability
budget
time constraints.
Media for user documentation


paper-based
online.
Types of Paper Based








user reference guide (manual)
trainer’s manual
brochure
student workbook
quick reference card
wall chart
keyboard overlay/template
terminal sticker
Types of Online








Online help
Online tutorial
Online manual
Wizard
Screen prompt/message
Navigation aid
Trouble-shooting information (bubble help)
CD-ROM and DVD
Standards


Standards ensure that levels of quality,
safety, reliability and efficiency are
incorporated into products and services when
they are developed and used.
Standards organisations, such as Standards
Australia, develop, monitor and maintain
standards in many areas of business and
industry.
ISO



ISO stands for the International Organisation
for Standardisation. This is a global
organisation that produces standards.
Members are government bodies, industry
associations and private organisations that
have an interest in industry standardisation.
Members reach consensus on standards for
industries that meet the needs of both
industries and consumers.
IEC


The International Electrotechnical
Commission (IEC) prepares and publishes
international standards for all electrical,
electronic and related technologies.
The IEC often works in conjunction with the
ISO to put standards together, particularly
standards for the IT industry
Australian Standards



Standards Australia is our organisation for the
development of national standards.
Standards Australia has developed its own
user documentation standard that is based on
the ISO/IEC standard.
AS4258 outlines the processes for creating all
forms of user documentation for software and
can be used as a contract with external
customers or between internal customers.
Designing Documents - Templates
Function and features of templates :
 helps to establish and maintain standards
 outlines the structure and format of the
document
 ensures standard text, diagrams and styles
 allows more than one person to work on the
document and maintain same structure.
Designing Documents – Style Guides
Information provided in a style guide includes

terminology

spelling

company/organisation and product names

problem words

abbreviations

acronyms

quotation marks

italics

numbers and symbols

punctuation

bullets and numbering

lists

headings

captions, figures and tables.
Software Tools

paper-based





word processing
desktop publishing
drawing
scanning
online



html editor
help files
web authoring.
Content








relaxed, conversational and personal style
active voice
correct spelling, grammar and punctuation
concise information
simple words, sentences and paragraphs
defined technical terms and jargon
positive language
supplementing with diagrams and pictures.
Proof Reading – Obtaining Sign-off


Proof-reading and review of documentation by:
appropriate company/organisation person/s






team leader/supervisor
editor
technical expert
trainer
experienced colleague
representative/s of the target audience.
Reviewers will consider




standards
style
consistency
content







clarity/readability
plain English
explanation of technical terms/jargon
accuracy
spelling, grammar and punctuation
usability
completeness.