- USER AND TECHNICAL DOCUMENTATION. Computer System Documentation What is documentation?What is documentation? –Communication designed to ease interaction.
USER AND TECHNICAL DOCUMENTATION. Computer System Documentation What is documentation?What is documentation? –Communication designed to ease interaction.
Slide 1 USER AND TECHNICAL DOCUMENTATION Slide 2 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. Slide 3 Computer System Documentation Types of DocumentationTypes of Documentation Technical and User TechnicalTechnical Printed /Online Hardware or software Specifications Texts and Diagrams Slide 4 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: Slide 5 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 Slide 6 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 Slide 7 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 Slide 8 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 Slide 9 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 Slide 10 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. Slide 11 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 Slide 12 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 Slide 13 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) Slide 14 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 Slide 15 Methodologies for producing documentation STANDARD DOCUMENTATION LIFE CYCLESTANDARD DOCUMENTATION LIFE CYCLE Planning Drafting Reviewing Testing Producing Distributing Updating Slide 16 Standard Documentation Process PLAN DRAFT REVIEW TEST PRODUCE UPDATE DISTRIBUTE Slide 17 Standard Documentation Process PlanningPlanning 1.Create a document library blueprint 2.Determine resources 3.Develop a schedule 4.Determine budget Slide 18 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 Slide 19 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 Slide 20 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 Slide 21 Standard Documentation Process Creating a document blueprint Related documentsRelated documents Online Printed Quick start Specs Detailed Slide 22 Standard Documentation Process Creating a document blueprint MediaMedia Appropriate media Type of user Use of application Slide 23 Standard Documentation Process Creating a document blueprint Production PlanProduction Plan How to produce Where to publish Slide 24 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 Slide 25 Standard Documentation Process Creating a document blueprint Update planUpdate plan How to keep the document updated. Slide 26 Standard Documentation Process PlanningPlanning 1.Create a document library blueprint 2.Determine resources 3.Develop a schedule 4.Determine budget Slide 27 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 Slide 28 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 Slide 29 Standard Documentation Process PLAN DRAFT REVIEW TEST PRODUCE UPDATE DISTRIBUTE Slide 30 Standard Documentation Process DraftingDrafting Creating the document, if required a few times Slide 31 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 Slide 32 Standard Documentation Process PLAN DRAFT REVIEW TEST PRODUCE UPDATE DISTRIBUTE Slide 33 Standard Documentation Process TestingTesting Tested by users Feed back is provided Corrections are noted Slide 34 Standard Documentation Process ProductionProduction Approval or sign off obtained Photocopy? Commercial Printer? Online Docs to be incorporated into application Slide 35 Standard Documentation Process DistributionDistribution Making it available to users of the system Put technical docs in packaging of product hardware CDs have to be printed and packaged Online help to be incorporated into software Slide 36 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 Slide 37 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 Slide 38 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) Slide 39 Standards Organisational StandardsOrganisational Standards Internal standards Project StandardsProject Standards Specific to project Slide 40 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