4. Create client user documentation and 5. Obtain endorsement/sign-off

1. 4. Create client user documentationand5. Obtain endorsement/sign-off 3651A Create User & Technical Documentation

2. User Documentation • This unit describes User Documentation in detail. User documentation is one form of support for users, and the requirements for documentation are many and varied. The different types of user documentation and their purpose are examined here. 3651A Create User & Technical Documentation

3. Types of user documentation • In unit 1 you learnt that user documentation can be printed or online, and assists people (that is, users) to use a computer system. You looked at different types of user documentation (instruction, training, policy and procedures). • User documentation can take various forms, depending on the needs of the audience and the scope of the project. The forms of documentation include: 3651A Create User & Technical Documentation

4. user’s reference guides • quick reference cards • handbooks • keyboard templates • wall charts • training manuals • computer-managed learning • computer-based training • tutorials • wizards • cue cards • frequently asked questions • glossaries • troubleshooting information • navigation aids • context-sensitive help • access to documentation on the Internet • intranet documentation. 3651A Create User & Technical Documentation

5. User’s Reference guide Containing comprehensive information about the software. There purpose is to: • enable users to learn how to use the software, • provide accurate reference info, • supply step-by-step details about how to complete tasks using the software, • help users understand their role in the process • explain why, as well as how a process is performed. It can be structured as task-based procedures or as menu-driven screen descriptions. 3651A Create User & Technical Documentation

6. Quick Reference cards Day to Day prompts of how to complete tasks. There purpose is to: • list key functions • act as a memory jogger about what to do next • summarise information • match the needs and level of expertise of specific users 3651A Create User & Technical Documentation

7. Handbooks Handbooks are scaled down documents that provide basic information to business partners or outside contractors who may need to supply or use data. Can also be written for software users who do not need the full details contained in the user’s reference manual. • Purpose is to • summarise key functions used by target audience • provide step-by-step instructions • help users to use the software confidently and accurately. 3651A Create User & Technical Documentation

8. Keyboard templates Some applications use the function keys on a standard keyboard to perform certain tasks. For example, pressing the Fl key initiates the Help function. Keyboard templates are cards that are sized to fit above the function keys on a standard keyboard. They help the user remember which keys to press for different functions. 3651A Create User & Technical Documentation

9. Wall charts • Wall charts are often useful for depicting the stages in a process. Thus, a group of users can see at a glance what should be done next, or who to notify when a process is completed. Wall charts are quick and easy to prepare and are popular with users, but are often forgotten when considering user documentation requirements. 3651A Create User & Technical Documentation

10. Training manuals Training manuals are usually only prepared when there is an organised training program. A training manual has a different role from that of a user’s reference guide, and requires a different approach. The purpose of a training manual is to: • build user acceptance of the software. Most people have an automatic reluctance to use or learn something new, and the training manual must make the transition easy and painless. 3651A Create User & Technical Documentation

11. provide users with customised working examples of how to perform a task using the software. This means that different training manuals must be prepared for each user group. The examples used for training data-entry clerks will be different from the examples used for training sales staff • lead the audience through the user’s reference guide, so that they have some familiarity with it and are therefore more likely to accept it and use it • provide a structure for trainers to follow so that the training delivery is consistent in content and approach • give realistic activities so that users can practise in a controlled environment. 3651A Create User & Technical Documentation

12. Computer-managed learning (CML) • Computer-managed learning (CML) is concerned with the online management of learning. In CML the computer is used to plan, organise, control, evaluate and assess what the student learns. Computer-managed learning can be used to select a study path for the student based on a combination of student performance and choice of options. 3651A Create User & Technical Documentation

13. Computer-based training (CBT) • Computer-based training (CBT) is also referred to as computer-assisted learning (CAL). It is concerned with presenting material and then testing the student with drills and practice. It is perhaps best described as an online tutorial that includes testing. 3651A Create User & Technical Documentation

14. Tutorials • Online tutorials come with many packages. They cannot be classified as CBT as they do not, in the main, assess the performance of the student. 3651A Create User & Technical Documentation

15. Wizards • Many software programs have assistants or wizards to help the user achieve particular tasks by answering a series of questions or prompts regarding the operation they want to accomplish. For example, you may create a database in Access 2002 using the wizards provided. 3651A Create User & Technical Documentation

16. Frequently asked questions (FAQ) • At the testing stages of a new product, different people often ask similar questions. To avoid technical support hotlines being asked the same question repeatedly, a section in the documentation may be devoted to frequently asked questions (FAQ). 3651A Create User & Technical Documentation

17. Glossaries • A feature of many Help systems is a glossary, where all the terminology relevant to the application is explained. A glossary can be helpful if a user (and their company) has a particular way of referring to things, or a package uses jargon. 3651A Create User & Technical Documentation

18. Troubleshooting information • This is where people turn to when the application is not functioning as it should or as the user expects it to. During the testing stage of software development, all the problems testers have discovered with the software can be analysed and described in the troubleshooting section. 3651A Create User & Technical Documentation

19. Navigation aids For some applications the online documentation is vast, and so being able to navigate around the documentation easily is very important. Helpful navigation aids include: • contents menus • indexes with A—Z buttons to go straight to the area of interest • browse sequences, in which related topics are grouped together so they can be skimmed using browse buttons (browsers) • search facilities to enable the user to find topics relating to a particular key word. 3651A Create User & Technical Documentation

20. Context-sensitive help • What the user wants is relevant help. Ideally, they should be able to find it immediately rather than having to search for it. Documentation on the Internet • Help can often be found on the Internet in the form of information about a product, answers to FAQ and so on. Websites can also provide fixes and upgrades for users to download. This is a cheap and effective means of distributing software. 3651A Create User & Technical Documentation

21. Intranet documentation • Many organisations are converting all their text-based files into HTML documents. This has the enormous advantage that anyone can view these documents. Prior to using HTML, if someone wanted to view a document written in PDF format, for example, they needed a copy of Acrobat Reader to view the document. 3651A Create User & Technical Documentation Activity 3.1

22. Purpose of User Documentation • In unit 1 you learnt that the purpose of user documentation is to support people who use a computer system, both hardware and software. Users require documentation in three ways: for training, to understand the computer system, and as a reference. These uses may be covered by just one item or by a set of specialised manuals, both written and online. 3651A Create User & Technical Documentation

23. Understanding • Users generally like to know something about a computer system before they use it. They may need this information to select or evaluate a product. An application also requires promotion to make potential users aware of its existence. 3651A Create User & Technical Documentation

24. Training • Most users require some form of training. Formal training sessions with a human trainer can be very effective, but often computer users do not attend them. Instead, lacking time and facilities for adequate training, many make do with a trial-and-error approach. • User documentation for training can come in any form of media. User manuals may include a tutorial section that takes the user through the steps of a common task or set of tasks. 3651A Create User & Technical Documentation

25. Reference • Users need to be able to refer to material that is specific and detailed enough to assist them with their tasks. This reference facility is vital. A function in an application may require a particular syntax or sequence of steps Activity 3.2 3651A Create User & Technical Documentation

26. Developing user documentation In unit 1, we looked at the standard documentation process, which consists of the following steps: • Planning. • Drafting. • Reviewing. • Testing. • Producing. • Distributing. • Updating. 3651A Create User & Technical Documentation

27. Before starting to write documentation, you should plan what to do. Planning now can help you provide documentation that satisfies the prime objective of supporting the user. Planning involves: • investigating the problem • defining the target audience — their skill level and needs • determining documentation requirements • designing the documentation • selecting suitable methods. 3651A Create User & Technical Documentation

28. Investigating the problem When deciding what documentation is required for a particular computer system, you need to find out more about the computer system to be documented. A number of questions need to be asked, such as: • Is the package a simple program, or is it likely to require a large amount of online assistance for a variety of users at different skill levels? • What operating system (s) is the software designed for? • I Is the product an upgrade of a previous version? If so, perhaps a ‘What’s new’ section may be required. 3651A Create User & Technical Documentation

29. The purpose of the documentation needs to be clearly stated. For example, for a sales support application it may be: To enable novice users to operate the three major functions of the application by following a step-by-step tutorial. To allow the average user to complete the tutorial in twenty minutes. To enable the user to: • add clients • search for and retrieve/modify client details. 3651A Create User & Technical Documentation

30. Defining the target audience • The intended audience or user must be identified, and their background and any other factors relevant to their use of the application stated. For example, language, culture, attitudes and work environment may be important. Are users familiar with the job that the software was designed to assist with? 3651A Create User & Technical Documentation

31. Novice: • A novice is a user who has not had any exposure to the application but must be able to become proficient in using it. Intermediate: • The intermediate user has had initial training. They have used the application to a degree where they are familiar with the major functions and can perform most of their duties with that application. 3651A Create User & Technical Documentation

32. Expert: • Expert users have had advanced training or have used the application for an extended period. They have extensive knowledge of the application and are proficient users. A reference card would be suitable. Casual: • Casual users use the application for specific functions on an irregular or infrequent basis. They only need to know a limited range of functions and should be able to use the application efficiently after lengthy absences. 3651A Create User & Technical Documentation

33. Determining documentation requirements • Having decided on the nature of the documentation required, you now need to design it. If you attempt to create the documentation without designing it properly first, a lot of work may need to be redone later. 3651A Create User & Technical Documentation

34. Your design should specify: • standards and styles — for text and graphics • graphics — how they will fit into the page layout • topics — which will be covered or addressed and at what level. This should be consistent with user needs and characteristics. • style and tone — these help determine the impression the documentation will make on the user. This should be compatible with such things as the language, culture and attitudes of the user. • typographic standards (for example, font size and type) — these will influence the reader’s ability to understand the documentation. 3651A Create User & Technical Documentation

35. Designing documentation is a three-stage process: • designing the overall structure of the help topics, also referred to as pages or screens • designing the links that enable navigation around the system • designing the contents of each screen. 3651A Create User & Technical Documentation

36. Selecting suitable tools to develop the documentation • Various tools are available for developing documentation. For printed documentation, they include word processing, desktop publishing, drawing and scanning software. Tools for producing online documentation include soft ware packages that generate Windows Help files (such as HDK, Help developers Kit), Internet or intranet documents (such as Microsoft’s Front Page) and online tutorials (such as Authorware). 3651A Create User & Technical Documentation

37. Drafting • Drafting is the actual writing (or authoring) of the documentation, and is usually the most time-consuming task. Several writing techniques can be used to make the documentation understandable to the user, and these are discussed in this section. • At the end of each day you should always back up your files. Every writer knows the frustration of files being corrupted or damaged and not adequately backed up. 3651A Create User & Technical Documentation

38. Reviewing • After the document has been drafted, various aspects including content, grammar and style should be checked. Someone other than the writer should do this, as the other person (or people) will see things that are not obvious to the writer. Professional publishers of documentation use several reviewers, including technical and language editors. 3651A Create User & Technical Documentation

39. Some of the things that are checked are: • Content • Is the information correct? Is there any information omitted that should be in? Is there any information that is irrelevant and should be omitted? • Grammar • Is the documentation grammatically correct? Are • there spelling errors? • Standards • Are organisational standards followed? • Clarity • Is the documentation clear and understandable to the reader? • Interest • Does the documentation hold the reader’s interest? 3651A Create User & Technical Documentation

40. 3651A Create User & Technical Documentation

41. Writing style • The style of writing is an important factor in determining the quality of documentation (both online and printed). The following features can influence how well the documentation is understood by the reader: • language • word simplicity • sentence and paragraph length • spelling and grammar • consistency • active voice • word emphasis. 3651A Create User & Technical Documentation

42. Printed documentation • Some criteria can be used to evaluate how effective the printed documentation is. Some of the criteria apply to all forms of documentation, and others apply specifically to printed documentation. Table 3.8 lists the evaluation criteria, with those specifically for printed documentation marked with an asterisk (*) 3651A Create User & Technical Documentation

43. Activity 3.5 3651A Create User & Technical Documentation

44. Online documentation • Criteria can also be used to evaluate the effectiveness of online documentation. Some apply to all forms of documentation and others specifically to online documentation. Table 3.9 lists evaluation criteria, with those specifically for online documentation marked with an asterisk (*). 3651A Create User & Technical Documentation

45. Activity 3.6 3651A Create User & Technical Documentation

46. Summary The three basic purposes of user documentation are understanding, training and reference. A general methodology has the following steps: • Planning. • Drafting. • Reviewing • Testing • Producing • Distributing • Updating. 3651A Create User & Technical Documentation

47. 4. Obtain endorsement/sign-off • Developed documentation is reviewed by target audience. After documentation has been completed it needs to be tested by the target audience to see if it tells the user all the relevant information to be able to use the software/device/etc • Changes are made according to target audience feedback. The document may have to be changed according to the problems that the target audience may have come across in their evaluation of the documentation 3651A Create User & Technical Documentation

48. Documentation is submitted for higher authority sign off • Once the documentation has been checked, rechecked and is ready for distribution it needs to be givento someone with the authority to say that it is complete and ready to be distributed. 3651A Create User & Technical Documentation