USER AND TECHNICAL DOCUMENTATION. Computer System Documentation What is documentation?What is...
-
Upload
austen-wilcox -
Category
Documents
-
view
239 -
download
1
Transcript of USER AND TECHNICAL DOCUMENTATION. Computer System Documentation What is documentation?What is...
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