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 DOCUMENTATION

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

Standard Documentation Process PLAN DRAFT REVIEW TEST PRODUCE UPDATE DISTRIBUTE Standard Documentation Process

Standard Documentation Process Planning Create a document library blueprint Determine resources Develop a schedule 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 Create a document library blueprint Determine resources Develop a schedule 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

Standard Documentation Process PLAN DRAFT REVIEW TEST PRODUCE UPDATE DISTRIBUTE Standard Documentation Process

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

Standard Documentation Process PLAN DRAFT REVIEW TEST PRODUCE UPDATE DISTRIBUTE Standard Documentation Process

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 Industry standards Organisational standards 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 Project Standards Internal standards Project Standards Specific to project

Templates and Documentation Tools 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