USER AND TECHNICAL DOCUMENTATION Computer System Documentation What

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

PLAN DRAFT Standard Documentation Process REVIEW TEST PRODUCE DISTRIBUTE UPDATE

Standard Documentation Process • Planning 1. 2. 3. 4. 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 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 person – 100 pages = 25 days by 1 person – @ $200 per day, total cost = $5000

PLAN DRAFT Standard Documentation Process REVIEW TEST 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 Documentation Process REVIEW TEST 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