1. Produce user documentation When a new computer application is implemented or changes are made to existing computer applications, documentation that explains how the computer application works may need to be provided directly to users and/or to the help desk.

2. Types of user documentation There are different types of documentation that can be available for each computer application, for example: 1user manual/guide 2technical manual/guide 3training manual/resources. When software is purchased off-the-shelf it usually comes with a user guide and technical guide. Training resources are then either purchased or developed in-house.

3. When computer applications are developed internally, a user guide, technical guide and training resources are usually developed to support the application. If the development is outsourced then the same supporting materials are usually developed as part of the project. Outsourcing occurs when external staff are hired to develop the computer application. Client documentation for software applications is generally prepared by the people/organisation who design and develop the application.

4. A user guide 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. Note that this guide can incorporate a training resource such as a tutorial.

5. The technical manual 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.

6. At the end of any project to develop a computer application, a copy of all documentation should be provided to: 1the client. 2the help desk. The help desk can then provide support to users when they contact them for support.

7. Providing support to clients for macros/templates Just like computer applications, macros and templates need to be supported by the help desk. When new templates have been developed or new macros set up in standard software packages, copies of the templates and lists of macro codes and purpose should be sent to the help desk.

8. When staff members contact the help desk because a template is being troublesome or a macro is not working, they can consult these documents to assist the staff member.

9. Reviewing the system, program, network or application Before you can start writing documentation, you need to know how the system, program, network and/or application that you are documenting works.

10. Using a user’s perspective The only way to find out how the system, program, network or application works is to become a user so that you become familiar with its features and you are confident in using it.

11. You should be looking at: the functionality — how it works the work processes surrounding its use — how the system works with organisational processes and procedures. Another valuable source of information are staff members who are already users or project team members who have been working with the system.

12. Gathering existing documentation If you are writing documentation for an existing system, program, network and/or application, some documentation may already exist. You should consult any existing documentation that may have accompanied the system (including technical information). This could include:

13. user guides project specifications online help procedure manuals. These documents will show you how the system, program, network or application works. It should also show you what the organisation’s work procedures are and how to apply them.

14. Writing effective user documentation As a confident user of the system you can begin to write the documentation using the agreed template and relevant tools. You will need a template for user documentation and the relevant tools for development.

15. Planning content In the same way that you plan any piece of writing, you will need to create a plan for writing the documentation. Before you write the user documentation, write an outline of the contents. Organise the content into: 1main headings 2sub headings 3points under each of the subheadings.

16. It might be necessary to approach a subject matter expert to assist with the planning or it might be sufficient to use any existing documentation as a model for the new documentation. When writing the content, it is important to follow effective writing principles. Other features such as graphic design and navigation will help user documentation work for users. Along with getting the content right, you’ll need to use sound principles for layout and usability as well.

17. A final stage in the development of your documentation will be testing the documentation with real users, then revising the documentation and testing it again. So you’ll have the opportunity to adjust content and other features to better fit the needs of your target users.

18. Think about the features that you have found useful in documentation. What were they?

19. Tips for writing and designing effective user documentation Use this as a checklist for planning the features of user documentation.

20. Content features Give a brief introduction where you state the purpose and objectives of the documentation. Include a table of contents or index. When writing, keep the users’ needs in mind, ie put yourself in the users’ place.

21. Ensure the content is accurate. Make clear sections for different types of features/information. Break the content down into easy-to-digest ‘chunks’, eg using paragraphs and sub headings, or multiple screens.

22. Use illustrations, diagrams, charts and/or screen shots where appropriate. State instructions clearly and step-by-step. Use plain English and avoid jargon.

23. Use technical terms only where necessary. Include a troubleshooting or help section. Include a glossary of the technical terms you have used.

24. Layout features Make the document structure as simple as possible and logical by providing cues to locate information. Ensure good usability, especially for online documentation.

25. Warnings, comments and help should be well-organised and visible. Aim for a clean design for text styles and layout that is consistent across all pages. Cross-reference information, eg use hyperlinks in online documentation.

26. Involving business units in the development of user documentation One of the reasons a project could fail is that people in the business units who will be impacted by the project’s implementation have been left out of the consultation process. From the beginning to end of a project, project team members need to work closely with users. They are an invaluable resource for developing documentation.

27. Though users and subject matter experts from the business units might not have the skills necessary to write effective documentation, they have the content knowledge. If you can tap into this knowledge your content will be accurate and relevant.

28. What do you think may be the benefits of involving users and accepting their feedback?

29. The end product is more closely aligned with the needs of the users. The process of creating user documentation is much simpler due to the expert knowledge users bring. Implementation and take-up of the new system, program, network or application is much greater with user involvement, as the subject matter experts can act as ‘champions’ within the business units.

30. Developer tools The writing tools you use will be determined by the medium — paper-based or online. Tools (software) can include applications for:

31. word processing image editing image conversion (to web-ready) painting and drawing HTML conversion/authoring/editing FTP utility site management software multimedia or slide show authoring audio and video equipment and editing software.

32. If you are developing paper- based materials, useful tools are: word processing software, eg Microsoft Word imaging software, eg Adobe Photoshop and/or Adobe Illustrator.

33. If your materials are going online, useful tools are: HTML conversion/authoring/editing Imaging software, eg Adobe Photoshop or Fireworks FTP utility, eg FTP Pro or CuteFTP.

34. Quality assurance (QA) Once the documentation has been written, a quality assurance check should be conducted before the draft is sent out for review. This check is best done by a subject matter expert, another member of the project team or a different writer.

35. QA checklist A standard checklist should be used to check the documentation. A QA checklist contains a list of standard formats and styles that reflect the organisation’s user documentation standards. The purpose of the checklist is to ensure the documentation standards are followed and that all user documentation is consistent in style and appearance. Once the QA is complete, the documentation can be sent for a formal review.

36. The following lists some of the criteria you could include in a QA checklist. Is the medium suitable? consider work practices, frequency of updates Are the purpose and objectives clear? objectives stated outcomes measurable achievable given the stated skill level of intended users Is the documentation suitable for the intended audience? plain language terms explained user-centred

37. Is the skill level of the user stated? skills required to understand and perform tasks specified Is the content complete and well organised? clear sections pages/screens numbered summaries included trouble shooting section included content matches objectives

38. Is it easy to access and navigate the information? Access points include: table of contents well-developed index with accurate matches cross referencing hot spots (online) Glossary legend to explain any symbols Are instructions clear? one task in one instruction instructions are numbered technical jargon avoided, explained where necessary, and located in the glossary

39. Logical flow of information topics build on the preceding topic and increase in level of difficulty Ease of use users can find what they are looking for users understand it users believe it is complete and accurate

40. Consistency in layout heading styles used consistently consistent use of fonts, type and size for both headings and body text font types limited to two or three consistent use of colour, paragraph styles, etc Balance of text and white space adequate use of white space information is easy to read and follow left justification been used

41. Visual cues adequate use of tables, illustrations, colour and other visual elements different kinds of information are clearly identified for easy reading eg –Heading –main body text instructions for user to perform a task at the computer explanations of tasks Warnings screen shots system messages comments to the user shortcuts to functions: function keys Presentation document looks interesting to read

42. Usability testing Online user documentation requires a test for usability. This means that the interactive design and navigation should be tested to see whether the user can easily find the information they are after.

43. It is preferable for usability testing to be performed by a subject matter expert or a user (since they will be using the documentation when it is finished). The organisation’s usability standards can be put into the QA checklist. Activities