USER AND TECHNICAL

DOCUMENTATION
 Computer System Documentation
• What is documentation?

– Communication designed to ease interaction

between computer software and individuals
who manage, audit, operate or maintain it.
 Computer System Documentation
• Types of Documentation
– Technical and User
• Technical
– Printed /Online –
– Hardware or software
– Specifications
– Texts and Diagrams
 Types of Documentation

• User
– Printed or Online
– shows people to use the computer system
– How to operate /install hardware
– texts and diags
Three types of user:
 Types of Documentation

• Three types of user:

– Instructional material
Accompanies product, H/w or S/w
How to use the product or some features

– Training material
Teaches people how to perform tasks or provides information about
computer related matter.

– Policy and procedures

Organisational rules, guidelines
Useful for new employees
Quality Assuarance
 Documentation Media
• Paper and Online

• Which one to use?- Usability –how well

does the documentation help the user
 Documentation Media
• Paper based
– Print Media
– Manuals
– Reference guides
– Brochures
Features and functions of equipment
How to install/setup
How to operate
Trouble shooting problems

USER AND TECHNICAL D

OCUMENTATION
 Documentation Media
• Online Documentation
Provided by the computer

• Internet
• Intranet
• Helpfiles
• Hypertext
• Smart - tags
• Wizards
• Multimedia –text Graphics, video, sound, interactive
• CD- Rom
 Purpose of Documentation
• TECHNICAL DOCUMENTATION
• Provides information on building, maintaining computer
systems
– Who uses technical documentation?
– Computer engineers
– Technicians
– systems anaylsts
– systems designers
– data analysts
– Programmers
– Technical / manual writers
– software testers
– Project managers
– System managers
– Computer operations staff
 Purpose of Documentation

• USER DOCUMENTATION
– Assists people in using computer systems
How to use system
Understand functions
Refer to specific functions

GUI – helps user ‘intuitively / instinctively use the

software.
 Purpose of Documentation

• To make it easy for users:

– Short cut keys for quick access, (right click)

– Navigation within an application using mouse, scroll
bar etc.
– Visual clues to guide user, smart tags, pop up
labelling
– Standard access to help – menus, help , prompts
– Multiple windows for related information
 Purpose of Documentation

• USER DOCUMENTATION
– One type may not suite all users
– Individual differences
– Rapidly changing technology
– Good documentation can be useful to users
 Methodologies for producing
documentation
• Methodology -The system of methods
followed in a particular discipline -A way of
doing something, esp. a systematic one;
implies an orderly logical arrangement
(usually in steps)
 Methodologies for producing
documentation
• Standard Documentation
– Steps:
– Document library blueprint
description of the different documentation required
Specification of the documentation to be produced
– Individual document blueprints
Identify the context, purpose and detailed content
 Methodologies for producing
documentation
• STANDARD DOCUMENTATION LIFE
CYCLE
– Planning
– Drafting
– Reviewing
– Testing
– Producing
– Distributing
– Updating
 PLAN

DRAFT

Standard REVIEW

Documentation
TEST
Process
PRODUCE

DISTRIBUTE

UPDATE
 Standard Documentation Process
• Planning
1. Create a document library blueprint
2. Determine resources
3. Develop a schedule
4. Determine budget
 Standard Documentation Process
• Creating a document blueprint
– Identifying all the pieces of documentation
and how they are related
– Document specification
– Provides information need to produce the
documentation
 Standard Documentation Process
Creating a document blueprint
• Document specification covers the documents:
– Purpose
– Audience
Characteristics
Needs
Diversity

• Related documents
• Media
• Production plan
• Reviewing and testing
• Update plan
 Standard Documentation Process
Creating a document blueprint
• Purpose of document defines the technical
problem being addressed in the context of
the business environment
• Reader
– Indentify
background,
Language,
Culture
Level of computer literacy
 Standard Documentation Process
Creating a document blueprint
• Related documents
– Online
– Printed
– Quick start
– Specs
– Detailed
 Standard Documentation Process
Creating a document blueprint
• Media
– Appropriate media
Type of user
Use of application
 Standard Documentation Process
Creating a document blueprint
• Production Plan
– How to produce
– Where to publish
 Standard Documentation Process
Creating a document blueprint
• Reviewing and testing
– Who will test and review
– Technical editors?
– Testing by the user and providing feedback
 Standard Documentation Process
Creating a document blueprint
• Update plan
– How to keep the document updated.
 Standard Documentation Process
• Planning
1. Create a document library blueprint
2. Determine resources
3. Develop a schedule
4. Determine budget
 Standard Documentation Process
• Determining resources required
– Information comes from various sources
Developers, programmers, users, policies, workpractices
Technical writers
Video producers
Dtp
Graphic artists
Animators
Programmers of online systems
CD ROM producers
 Standard Documentation Process
• Developing Schedule
– List of tasks and order

• Determining the budget

– Usually 10 to 20% of the product cost
– 1 -8 pages per day per person
– 100 pages = 25days by 1 person
– @ $200 per day, total cost = $5000
 PLAN

DRAFT

Standard REVIEW

Documentation
TEST
Process
PRODUCE

DISTRIBUTE

UPDATE
 Standard Documentation Process
• Drafting
– Creating the document, if required a few times
Standard Documentation Process

• Reviewing
– Purpose – objectives met?
– Content
Subject area covered
Any omissions
Unnecessary detail
Errors
appropriate for user
– Grammar – errors
– Clarity – clear explanation
– Style – appropriate for intended user
– Usually needs a few drafts
 PLAN

DRAFT

Standard REVIEW

Documentation
TEST
Process
PRODUCE

DISTRIBUTE

UPDATE
 Standard Documentation Process
• Testing
– Tested by users
– Feed back is provided
– Corrections are noted
 Standard Documentation Process
• Production
– Approval or sign off obtained
– Photocopy?
– Commercial Printer?
– Online Docs to be incorporated into
application
 Standard Documentation Process
• Distribution
– Making it available to users of the system
– Put technical docs in packaging of product –
hardware
– CD’s have to be printed and packaged
– Online help to be incorporated into software
 Standard Documentation Process
• Updating
– Ever changing environment of the computer
world – update docs all the time
– Also improvements can be done based on
feedback

• Version control –
– Different versions of product – ensure they
have match documentation
 Standards
• Guidelines for producing documents
• Provides consistancy of documentation
• Quality of product

1. Industry standards
2. Organisational standards
3. Project standards
 Standards
• Industry standards
– Standards Australia describe basic
documentation requirements to enable quality
standards to be met.
– Standards for user documentation:
Software user documentation process (ref:
AS/NZS 4258:1994)
 Standards
• Organisational Standards
– Internal standards

• Project Standards
– Specific to project
 Templates and Documentation
Tools
• Templates
– Outline containing the structure and format of a
document - guideline
Saves time

• Documentation Tools
– Word
– Pagemaker, Publisher
– Help developers kit – HDK
– HTML
– Front Page
– Visio