USER AND TECHNICAL DOCUMENTATION

Computer System Documentation What is 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 DocumentationTypes of Documentation –Technical and User TechnicalTechnical –Printed /Online – –Hardware or software –Specifications –Texts and Diagrams

Types of Documentation UserUser –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: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 OnlinePaper and Online Which one to use?- Usability –how well does the documentation help the userWhich one to use?- Usability –how well does the documentation help the user

USER AND TECHNICAL DOCUMENTATION Documentation Media Paper basedPaper based –Print Media –Manuals –Reference guides –Brochures Features and functions of equipment How to install/setup How to operate Trouble shooting problems

Documentation Media Online DocumentationOnline Documentation Provided by the computer InternetInternet IntranetIntranet HelpfilesHelpfiles HypertextHypertext Smart - tagsSmart - tags WizardsWizards Multimedia –text Graphics, video, sound, interactiveMultimedia –text Graphics, video, sound, interactive CD- RomCD- Rom

Purpose of Documentation TECHNICAL DOCUMENTATIONTECHNICAL DOCUMENTATION Provides information on building, maintaining computer systemsProvides 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 DOCUMENTATIONUSER 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: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 DOCUMENTATIONUSER 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)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 DocumentationStandard 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 CYCLESTANDARD DOCUMENTATION LIFE CYCLE –Planning –Drafting –Reviewing –Testing –Producing –Distributing –Updating

Standard Documentation Process PLAN DRAFT REVIEW TEST PRODUCE UPDATE DISTRIBUTE

Standard Documentation Process PlanningPlanning 1.Create a document library blueprint 2.Determine resources 3.Develop a schedule 4.Determine budget

Standard Documentation Process Creating a document blueprintCreating 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:Document specification covers the documents: –Purpose –Audience CharacteristicsNeedsDiversity Related documentsRelated documents MediaMedia Production planProduction plan Reviewing and testingReviewing and testing Update planUpdate plan

Standard Documentation Process Creating a document blueprint Purpose of document defines the technical problem being addressed in the context of the business environmentPurpose of document defines the technical problem being addressed in the context of the business environment ReaderReader –Indentify background,Language,Culture Level of computer literacy

Standard Documentation Process Creating a document blueprint Related documentsRelated documents –Online –Printed –Quick start –Specs –Detailed

Standard Documentation Process Creating a document blueprint MediaMedia –Appropriate media Type of user Use of application

Standard Documentation Process Creating a document blueprint Production PlanProduction Plan –How to produce –Where to publish

Standard Documentation Process Creating a document blueprint Reviewing and testingReviewing and testing –Who will test and review –Technical editors? –Testing by the user and providing feedback

Standard Documentation Process Creating a document blueprint Update planUpdate plan –How to keep the document updated.

Standard Documentation Process PlanningPlanning 1.Create a document library blueprint 2.Determine resources 3.Develop a schedule 4.Determine budget

Standard Documentation Process Determining resources requiredDetermining 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 ScheduleDeveloping Schedule –List of tasks and order Determining the budgetDetermining 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 DraftingDrafting –Creating the document, if required a few times

Standard Documentation Process ReviewingReviewing –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 TestingTesting –Tested by users –Feed back is provided –Corrections are noted

Standard Documentation Process ProductionProduction –Approval or sign off obtained –Photocopy? –Commercial Printer? –Online Docs to be incorporated into application

Standard Documentation Process DistributionDistribution –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 UpdatingUpdating –Ever changing environment of the computer world – update docs all the time –Also improvements can be done based on feedback Version control –Version control – –Different versions of product – ensure they have match documentation

Standards Guidelines for producing documentsGuidelines for producing documents Provides consistancy of documentationProvides consistancy of documentation Quality of productQuality of product 1.Industry standards 2.Organisational standards 3.Project standards

Standards Industry standardsIndustry 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 StandardsOrganisational Standards –Internal standards Project StandardsProject Standards –Specific to project

Templates and Documentation Tools TemplatesTemplates –Outline containing the structure and format of a document - guideline Saves time Documentation ToolsDocumentation Tools –Word –Pagemaker, Publisher –Help developers kit – HDK –HTML –Front Page –Visio