USER AND TECHNICAL DOCUMENTATION

1. USER AND TECHNICAL DOCUMENTATION

2. Computer System Documentation • What is documentation? • Communication designed to ease interaction between computer software and individuals who manage, audit, operate or maintain it.

3. Computer System Documentation • Types of Documentation • Technical and User • Technical • Printed /Online – • Hardware or software • Specifications • Texts and Diagrams

4. 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:

5. 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

6. Documentation Media • Paper and Online • Which one to use?- Usability –how well does the documentation help the user

7. 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

8. Documentation Media • Online Documentation Provided by the computer • Internet • Intranet • Helpfiles • Hypertext • Smart - tags • Wizards • Multimedia –text Graphics, video, sound, interactive • CD- Rom

9. 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

10. 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.

11. 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

12. Purpose of Documentation • USER DOCUMENTATION • One type may not suite all users • Individual differences • Rapidly changing technology • Good documentation can be useful to users

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)

14. 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

15. Methodologies for producing documentation • STANDARD DOCUMENTATION LIFE CYCLE • Planning • Drafting • Reviewing • Testing • Producing • Distributing • Updating

16. PLAN DRAFT REVIEW TEST PRODUCE DISTRIBUTE UPDATE Standard Documentation Process

17. Standard Documentation Process • Planning • Create a document library blueprint • Determine resources • Develop a schedule • Determine budget

18. 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

19. 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

20. 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

21. Standard Documentation Process Creating a document blueprint • Related documents • Online • Printed • Quick start • Specs • Detailed

22. Standard Documentation Process Creating a document blueprint • Media • Appropriate media • Type of user • Use of application

23. Standard Documentation Process Creating a document blueprint • Production Plan • How to produce • Where to publish

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

25. Standard Documentation Process Creating a document blueprint • Update plan • How to keep the document updated.

26. Standard Documentation Process • Planning • Create a document library blueprint • Determine resources • Develop a schedule • Determine budget

27. 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

28. 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 per person • 100 pages = 25days by 1 person • @ $200 per day, total cost = $5000

29. PLAN DRAFT REVIEW TEST PRODUCE DISTRIBUTE UPDATE Standard Documentation Process

30. Standard Documentation Process • Drafting • Creating the document, if required a few times

31. 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

32. PLAN DRAFT REVIEW TEST PRODUCE DISTRIBUTE UPDATE Standard Documentation Process

33. Standard Documentation Process • Testing • Tested by users • Feed back is provided • Corrections are noted

34. Standard Documentation Process • Production • Approval or sign off obtained • Photocopy? • Commercial Printer? • Online Docs to be incorporated into application

35. 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

36. 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

37. Standards • Guidelines for producing documents • Provides consistancy of documentation • Quality of product • Industry standards • Organisational standards • Project standards

38. 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)

39. Standards • Organisational Standards • Internal standards • Project Standards • Specific to project

40. 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