1 / 36

Create User Documentation

Create User Documentation. ICAD3218A. Procedure for Creating User Documentation. Determine documentation standards and requirements Produce user documentation Review and obtain sign-off. Key Concepts and Terms. ICAD3218A - Create User Documentation. appropriate person/s approval

zahir-best
Download Presentation

Create User Documentation

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript


  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.

More Related