1. Create User Documentation
ICAD3218A

2. Procedure for Creating User Documentation
Determine documentation standards and requirements
Produce user documentation
Review and obtain sign-off

3. Key Concepts and Terms ICAD3218A - Create User Documentation
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.

4. 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)

5. 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.
Brochures
outline what a computer application does

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

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

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

9. 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).

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

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

12. Why documentation fails
Documentation can fail due to :
user attitude
management attitude
writer’s attitude

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

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

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

16. Effective documentation will :
Take into consideration the differences between target audience (users)
personalities
experience
cultural background
attitudes and values
language
environment

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

18. Consider the User (Continued)
User characteristic
User need
Possible solutions
cultural background
language appropriate to some users may not be appropriate for others
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

19. 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).

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

21. Effective documentation will :
show the user how to
call information to the screen
manipulate the information
store the information as required

22. The documentation process
The Steps for creating user documentation :
plan
draft
review/edit
test
produce
distribute
maintain/revise.

23. Points to consider when creating documentation
user’s needs
appropriateness to task
usability
budget
time constraints.

24. Media for user documentation
paper-based
online.

25. Types of Paper Based user reference guide (manual) trainer’s manual
brochure
student workbook
quick reference card
wall chart
keyboard overlay/template
terminal sticker

26. Types of Online Online help Online tutorial Online manual Wizard
Screen prompt/message
Navigation aid
Trouble-shooting information (bubble help)
CD-ROM and DVD

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

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

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

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

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

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

33. Software Tools paper-based online word processing desktop publishing
drawing
scanning
online
html editor
help files
web authoring.

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

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

36. Reviewers will consider
standards
style
consistency
content
clarity/readability
plain English
explanation of technical terms/jargon
accuracy
spelling, grammar and punctuation
usability
completeness.