Create User Documentation

1. Create User Documentation ICAD3218A

2. Procedure for Creating User Documentation • Determine documentation standards and requirements • Produce user documentation • Review and obtain sign-off

3. Key Concepts and Terms ICAD3218A - Create User Documentation • appropriate person/s • approval • blueprint • characteristics of effective user documentation • create user documentation • documentation process • documentation requirements • function and features of templates • gather and analyse feedback • general features, benefits and limitations of paper-based and online user documentation • general features, benefits, limitations and working knowledge of software tools/packages • identify and clarify needs of the target audience • investigation and research into the system/platform/network/application to be documented • naming standards • points to consider when writing content • principles of instructional, document and web design • proof-reading and review of user documentation • purpose of user documentation • standards • storage, distribution and maintenance/ review of user documentation • style guides • target audience • tracking processes • types of user documentation • user documentation • version control.

4. Types of user documentation There are different types of documentation that can be available for a computer application, for example: • user manual/guide (usually comes bundled with software) • technical manual/guide (usually comes bundled with software) • training manual/resources (usually purchased separately or developed in-house)

5. Types of Documentation

6. User Guide A userguide shows the user: • how to use the application, ie the steps required to complete various tasks • screens dumps with ‘dummy’ data to give the user a complete picture of how to enter data and process the data • tutorials.

7. Technical Manual The technicalmanual generally contains the technical information such as: • system requirements to run the application • how to install the application • configuring the application • database layout (if a database is used) • screen layouts • how to get technical support.

8. Purpose of documentation • providing instruction for use of hardware and software Technologies • training resource for better use of Technologies • recording of policies and procedures in the business • reference/source of information. Computer users need documentation so that they can make the best use of their computers as work tools • learn how to use the system and its applications • know how to get help when they need to learn more • know what to do when they experience problems.

9. Types of user documentation. Documentation can be : • paper-based, or • Online There are two broad audiences for documentation : • internal (for in-house use, used by the same company/organisation that develops it) • external (for outside use, for users outside the company/organisation that develops it).

10. What does documentation look like Books, manuals, computer-based tutorials and online help are all media for user documentation. Documentation now being moved to electronic form because : • increased productivity — users have up-to-date, comprehensive information that they can access quickly and easily. • increased corporate intelligence — information is stored centrally but distributed universally • consistency and quality — documentation appears in the same format and is easily updateable • reduced printing costs.

11. If documentation is ineffective or not provided Ineffective documentation can: • reduce efficiency – staff spend time trying to work out how to perform tasks • waste resources – staff can work inefficiently and waste time or other resources • increase costs of training – training is expensive and it is cheaper to provide staff with documentation so they can teach themselves • users reject a system that they don’t understand or find difficult to use

12. Why documentation fails Documentation can fail due to : • user attitude • management attitude • writer’s attitude

13. Failure due to user’s attitude Users will reject documentation for various reasons including : • User finds it too hard to find information • User finds documentation too difficult to understand • The documentation contains information that is old • User is too lazy to look • User is turned off because manual is too thick

14. Failure due to Management Attitude Documentation can fail due to the attitude of management including • Time constraints placed upon the user or the developer of the document • budget constraints placed upon the developer of the documentation or not purchaising sufficent documentation (eg buying only technical manuals and no training guides) • failing to communicate with technical staff during the design of the documentation or encourage user to use documentation. • not highly valued – not supporting the developer or the staff using the documentation.

15. Failure due to writer’s attitude The writer’s attitude can effect the documentation by : • not taking enough time to understand the system before writing • more concerned about the look of the document (design factors) than content.

16. Effective documentation will : Take into consideration the differences between target audience (users) • personalities • experience • cultural background • attitudes and values • language • environment

17. Consider the User

18. Consider the User (Continued)

19. Effective documentation will : • see everything from the user’s point of view • be available in a form and place that users can refer to when needed • Know and understand its target audience (set of users).

20. Effective documentation will : have information that is • easy to find • easy to comprehend • up-to-date, reflecting latest changes and revisions to the system • reliable and convincing

21. Effective documentation will : show the user how to • call information to the screen • manipulate the information • store the information as required

22. The documentation process The Steps for creating user documentation : • plan • draft • review/edit • test • produce • distribute • maintain/revise.

23. Points to consider when creating documentation • user’s needs • appropriateness to task • usability • budget • time constraints.

24. Media for user documentation • paper-based • online.

25. Types of Paper Based • user reference guide (manual) • trainer’s manual • brochure • student workbook • quick reference card • wall chart • keyboard overlay/template • terminal sticker

26. Types of Online • Online help • Online tutorial • Online manual • Wizard • Screen prompt/message • Navigation aid • Trouble-shooting information (bubble help) • CD-ROM and DVD

27. Standards • Standards ensure that levels of quality, safety, reliability and efficiency are incorporated into products and services when they are developed and used. • Standards organisations, such as Standards Australia, develop, monitor and maintain standards in many areas of business and industry.

28. ISO • ISO stands for the International Organisation for Standardisation. This is a global organisation that produces standards. • Members are government bodies, industry associations and private organisations that have an interest in industry standardisation. • Members reach consensus on standards for industries that meet the needs of both industries and consumers.

29. IEC • The International Electrotechnical Commission (IEC) prepares and publishes international standards for all electrical, electronic and related technologies. • The IEC often works in conjunction with the ISO to put standards together, particularly standards for the IT industry

30. Australian Standards • Standards Australia is our organisation for the development of national standards. • Standards Australia has developed its own user documentation standard that is based on the ISO/IEC standard. • AS4258 outlines the processes for creating all forms of user documentation for software and can be used as a contract with external customers or between internal customers.

31. Designing Documents - Templates Function and features of templates : • helps to establish and maintain standards • outlines the structure and format of the document • ensures standard text, diagrams and styles • allows more than one person to work on the document and maintain same structure.

32. Designing Documents – Style Guides Information provided in a style guide includes • terminology • spelling • company/organisation and product names • problem words • abbreviations • acronyms • quotation marks • italics • numbers and symbols • punctuation • bullets and numbering • lists • headings • captions, figures and tables.

33. Software Tools • paper-based • word processing • desktop publishing • drawing • scanning • online • html editor • help files • web authoring.

34. Content • relaxed, conversational and personal style • active voice • correct spelling, grammar and punctuation • concise information • simple words, sentences and paragraphs • defined technical terms and jargon • positive language • supplementing with diagrams and pictures.

35. Proof Reading – Obtaining Sign-off • Proof-reading and review of documentation by: • appropriate company/organisation person/s • team leader/supervisor • editor • technical expert • trainer • experienced colleague • representative/s of the target audience.

36. Reviewers will consider • standards • style • consistency • content • clarity/readability • plain English • explanation of technical terms/jargon • accuracy • spelling, grammar and punctuation • usability • completeness.