USER AND TECHNICAL USER AND TECHNICAL DOCUMENTATIONDOCUMENTATION

Computer System DocumentationComputer System Documentation

• What is documentation?What is documentation?

– Communication designed to ease interaction Communication designed to ease interaction between computer software and individuals between computer software and individuals who manage, audit, operate or maintain it.who manage, audit, operate or maintain it.

Computer System DocumentationComputer System Documentation

• Types of DocumentationTypes of Documentation– Technical and UserTechnical and User

• TechnicalTechnical– Printed /Online –Printed /Online –– Hardware or softwareHardware or software– SpecificationsSpecifications– Texts and DiagramsTexts and Diagrams

Types of DocumentationTypes of Documentation

• UserUser– Printed or OnlinePrinted or Online– shows people to use the computer system shows people to use the computer system – How to operate /install hardwareHow to operate /install hardware– texts and diagstexts and diags

Three types of user:Three types of user:

Types of DocumentationTypes of Documentation

• Three types of user:Three types of user:

– Instructional materialInstructional materialAccompanies product, H/w or S/wAccompanies product, H/w or S/wHow to use the product or some featuresHow to use the product or some features

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

– Policy and proceduresPolicy and proceduresOrganisational rules, guidelinesOrganisational rules, guidelinesUseful for new employeesUseful for new employeesQuality AssuaranceQuality Assuarance

Documentation MediaDocumentation Media

• Paper and OnlinePaper and Online

• Which one to use?- Usability –how well Which one to use?- Usability –how well does the documentation help the userdoes the documentation help the user

USER AND TECHNICAL DUSER AND TECHNICAL DOCUMENTATIONOCUMENTATION

Documentation MediaDocumentation Media

• Paper basedPaper based– Print MediaPrint Media– ManualsManuals– Reference guidesReference guides– BrochuresBrochures

Features and functions of equipmentFeatures and functions of equipment

How to install/setupHow to install/setup

How to operateHow to operate

Trouble shooting problemsTrouble shooting problems

Documentation MediaDocumentation Media

• Online DocumentationOnline DocumentationProvided by the computer Provided by the computer

• InternetInternet• IntranetIntranet• HelpfilesHelpfiles• Hypertext Hypertext • Smart - tagsSmart - tags• WizardsWizards• Multimedia –text Graphics, video, sound, interactiveMultimedia –text Graphics, video, sound, interactive• CD- RomCD- Rom

Purpose of DocumentationPurpose of Documentation• TECHNICAL DOCUMENTATIONTECHNICAL DOCUMENTATION• Provides information on building, maintaining computer Provides information on building, maintaining computer

systemssystems– Who uses technical documentation?Who uses technical documentation?– Computer engineersComputer engineers– TechniciansTechnicians– systems anaylstssystems anaylsts– systems designerssystems designers– data analystsdata analysts– ProgrammersProgrammers– Technical / manual writersTechnical / manual writers– software testerssoftware testers– Project managersProject managers– System managersSystem managers– Computer operations staffComputer operations staff

Purpose of DocumentationPurpose of Documentation

• USER DOCUMENTATIONUSER DOCUMENTATION– Assists people in using computer systemsAssists people in using computer systems

How to use systemHow to use system

Understand functionsUnderstand functions

Refer to specific functionsRefer to specific functions

GUI – helps user ‘intuitively / instinctively use the GUI – helps user ‘intuitively / instinctively use the software.software.

Purpose of DocumentationPurpose of Documentation

• To make it easy for users:To make it easy for users:

– Short cut keys for quick access, (right click)Short cut keys for quick access, (right click)– Navigation within an application using mouse, scroll Navigation within an application using mouse, scroll

bar etc.bar etc.– Visual clues to guide user, smart tags, pop up Visual clues to guide user, smart tags, pop up

labellinglabelling– Standard access to help – menus, help , promptsStandard access to help – menus, help , prompts– Multiple windows for related informationMultiple windows for related information

Purpose of DocumentationPurpose of Documentation

• USER DOCUMENTATIONUSER DOCUMENTATION– One type may not suite all usersOne type may not suite all users– Individual differencesIndividual differences– Rapidly changing technologyRapidly changing technology– Good documentation can be useful to usersGood documentation can be useful to users

Methodologies for producing Methodologies for producing documentationdocumentation

• Methodology -The system of methods Methodology -The system of methods followed in a particular discipline -A way of followed in a particular discipline -A way of doing something, esp. a systematic one; doing something, esp. a systematic one; implies an orderly logical arrangement implies an orderly logical arrangement (usually in steps)(usually in steps)

Methodologies for producing Methodologies for producing documentationdocumentation

• Standard DocumentationStandard Documentation– Steps:Steps:– Document library blueprintDocument library blueprint

description of the different documentation required description of the different documentation required

Specification of the documentation to be producedSpecification of the documentation to be produced

– Individual document blueprintsIndividual document blueprintsIdentify the context, purpose and detailed contentIdentify the context, purpose and detailed content

Methodologies for producing Methodologies for producing documentationdocumentation

• STANDARD DOCUMENTATION LIFE STANDARD DOCUMENTATION LIFE CYCLECYCLE– PlanningPlanning– Drafting Drafting – Reviewing Reviewing – Testing Testing – ProducingProducing– DistributingDistributing– UpdatingUpdating

Standard Standard Documentation Documentation

ProcessProcess

PLAN

DRAFT

REVIEW

TEST

PRODUCE

UPDATE

DISTRIBUTE

Standard Documentation ProcessStandard Documentation Process

• PlanningPlanning1.1. Create a document library blueprintCreate a document library blueprint

2.2. Determine resources Determine resources

3.3. Develop a scheduleDevelop a schedule

4.4. Determine budgetDetermine budget

Standard Documentation ProcessStandard Documentation Process

• Creating a document blueprintCreating a document blueprint– Identifying all the pieces of documentation Identifying all the pieces of documentation

and how they are related and how they are related – Document specificationDocument specification– Provides information need to produce the Provides information need to produce the

documentationdocumentation

Standard Documentation Process Standard Documentation Process Creating a document blueprintCreating a document blueprint

• Document specification covers the documents:Document specification covers the documents:– PurposePurpose– AudienceAudience

CharacteristicsCharacteristicsNeedsNeedsDiversityDiversity

• Related documentsRelated documents• MediaMedia• Production planProduction plan• Reviewing and testingReviewing and testing• Update planUpdate plan

Standard Documentation Process Standard Documentation Process Creating a document blueprintCreating a document blueprint

• Purpose of document defines the technical Purpose of document defines the technical problem being addressed in the context of problem being addressed in the context of the business environmentthe business environment

• ReaderReader– IndentifyIndentify

background,background,

Language,Language,

CultureCulture

Level of computer literacyLevel of computer literacy

Standard Documentation Process Standard Documentation Process Creating a document blueprintCreating a document blueprint

• Related documentsRelated documents– OnlineOnline– PrintedPrinted– Quick startQuick start– Specs Specs – DetailedDetailed

Standard Documentation Process Standard Documentation Process Creating a document blueprintCreating a document blueprint

• MediaMedia– Appropriate mediaAppropriate media

Type of userType of user

Use of applicationUse of application

Standard Documentation Process Standard Documentation Process Creating a document blueprintCreating a document blueprint

• Production PlanProduction Plan– How to produceHow to produce– Where to publishWhere to publish

Standard Documentation Process Standard Documentation Process Creating a document blueprintCreating a document blueprint

• Reviewing and testingReviewing and testing– Who will test and reviewWho will test and review– Technical editors?Technical editors?– Testing by the user and providing feedbackTesting by the user and providing feedback

Standard Documentation Process Standard Documentation Process Creating a document blueprintCreating a document blueprint

• Update planUpdate plan– How to keep the document updated.How to keep the document updated.

Standard Documentation ProcessStandard Documentation Process

• PlanningPlanning1.1. Create a document library blueprintCreate a document library blueprint

2.2. Determine resources Determine resources 3.3. Develop a scheduleDevelop a schedule

4.4. Determine budgetDetermine budget

Standard Documentation ProcessStandard Documentation Process

• Determining resources requiredDetermining resources required– Information comes from various sourcesInformation comes from various sources

Developers, programmers, users, policies, workpracticesDevelopers, programmers, users, policies, workpractices

Technical writersTechnical writers

Video producersVideo producers

DtpDtp

Graphic artistsGraphic artists

AnimatorsAnimators

Programmers of online systemsProgrammers of online systems

CD ROM producersCD ROM producers

Standard Documentation ProcessStandard Documentation Process

• Developing ScheduleDeveloping Schedule– List of tasks and orderList of tasks and order

• Determining the budgetDetermining the budget– Usually 10 to 20% of the product costUsually 10 to 20% of the product cost– 1 -8 pages per day per person1 -8 pages per day per person– 100 pages = 25days by 1 person100 pages = 25days by 1 person– @ $200 per day, total cost = $5000@ $200 per day, total cost = $5000

Standard Standard Documentation Documentation

ProcessProcess

PLAN

DRAFT

REVIEW

TEST

PRODUCE

UPDATE

DISTRIBUTE

Standard Documentation ProcessStandard Documentation Process

• DraftingDrafting– Creating the document, if required a few timesCreating the document, if required a few times

Standard Documentation Process Standard Documentation Process

• ReviewingReviewing– Purpose – objectives met?Purpose – objectives met?– ContentContent

Subject area coveredSubject area coveredAny omissionsAny omissionsUnnecessary detailUnnecessary detailErrorsErrorsappropriate for userappropriate for user

– Grammar – errorsGrammar – errors– Clarity – clear explanationClarity – clear explanation– Style – appropriate for intended userStyle – appropriate for intended user– Usually needs a few draftsUsually needs a few drafts

Standard Standard Documentation Documentation

ProcessProcess

PLAN

DRAFT

REVIEW

TEST

PRODUCE

UPDATE

DISTRIBUTE

Standard Documentation ProcessStandard Documentation Process

• TestingTesting– Tested by usersTested by users– Feed back is provided Feed back is provided – Corrections are notedCorrections are noted

Standard Documentation ProcessStandard Documentation Process

• ProductionProduction– Approval or sign off obtained Approval or sign off obtained – Photocopy?Photocopy?– Commercial Printer?Commercial Printer?– Online Docs to be incorporated into Online Docs to be incorporated into

applicationapplication

Standard Documentation ProcessStandard Documentation Process

• DistributionDistribution– Making it available to users of the systemMaking it available to users of the system– Put technical docs in packaging of product –Put technical docs in packaging of product –

hardwarehardware– CD’s have to be printed and packagedCD’s have to be printed and packaged– Online help to be incorporated into softwareOnline help to be incorporated into software

Standard Documentation ProcessStandard Documentation Process

• UpdatingUpdating– Ever changing environment of the computer Ever changing environment of the computer

world – update docs all the timeworld – update docs all the time– Also improvements can be done based on Also improvements can be done based on

feedbackfeedback

• Version control – Version control – – Different versions of product – ensure they Different versions of product – ensure they

have match documentationhave match documentation

StandardsStandards

• Guidelines for producing documentsGuidelines for producing documents

• Provides consistancy of documentationProvides consistancy of documentation

• Quality of productQuality of product

1.1. Industry standardsIndustry standards

2.2. Organisational standardsOrganisational standards

3.3. Project standardsProject standards

StandardsStandards

• Industry standardsIndustry standards– Standards Australia describe basic Standards Australia describe basic

documentation requirements to enable quality documentation requirements to enable quality standards to be met.standards to be met.

– Standards for user documentation:Standards for user documentation:Software user documentation process (ref: Software user documentation process (ref: AS/NZS 4258:1994) AS/NZS 4258:1994)

StandardsStandards

• Organisational StandardsOrganisational Standards– Internal standardsInternal standards

• Project StandardsProject Standards– Specific to projectSpecific to project

Templates and Documentation Templates and Documentation ToolsTools

• TemplatesTemplates– Outline containing the structure and format of a Outline containing the structure and format of a

document - guidelinedocument - guidelineSaves timeSaves time

• Documentation ToolsDocumentation Tools– WordWord– Pagemaker, PublisherPagemaker, Publisher– Help developers kit – HDKHelp developers kit – HDK– HTMLHTML– Front PageFront Page– VisioVisio