Upload
posy-mckenzie
View
272
Download
3
Tags:
Embed Size (px)
Citation preview
Create User Documentation ICAD3218A
Procedure for Creating User Documentation Determine documentation standards and
requirements Produce user documentation Review and obtain sign-off
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.
ICAD3218A - Create User Documentation
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 DocumentationDocumentation 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
User GuideA 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 ManualThe 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 likeBooks, 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 providedIneffective 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 failsDocumentation can fail due to : user attitude management attitude writer’s attitude
Failure due to user’s attitudeUsers 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 AttitudeDocumentation 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 attitudeThe 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 UserUser 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
• 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
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 - TemplatesFunction 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 GuidesInformation 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.