There is always a need for training documentation, be it a How-To or Quick Reference Guide or a full User Guide/Manual. It may be for the end users or for the trainer, or to accompany and support E-learning. The end users need some way of referring to the topics that they learned on the course, especially for processes and actions that are carried out infrequently and therefore do not become second nature. The trainer(s) need some sort of a script to follow so that the training is consistent and the same topics taught in the same way with the most appropriate exercises. We refer to this as the Trainer’s Toolkit and it includes things such as a Lesson Plan with order of topics and a basic script, with key learning points and reference to the appropriate sections in a User Guide if appropriate and of course answers to the exercises. It may also include a PowerPoint presentation with the key topics used to introduce each new section and the learning objectives for those topics. Ideally, throughout the training, reference should be made to the end user documentation, so that they know where to locate it in the future and have familiarised themselves with the contents and layout.
In many projects that we have worked on, there has been a great emphasis on creating user documentation in the form of a manual that is either hard copy or posted online on an intranet or as E-learning reference material. It is a wonderful feeling to create something that others look at and tell you that it is useful. What about the shelf life though, the continuing updates and maintenance? Who will take on that responsibility in addition to their normal job? As an external consultant can you walk away from a project having full confidence that if you went back after 6 months or a year, users would know where the documentation was, know that it was up to date and confirm that they referred to it? Sadly, I think not.
There are a lot of documented procedures and processes and rules and regulations that are often used as source material in the creation of user documentation. Consider this… if the process or rules change, then those documents need to change and then so does the end-user training documentation. All time consuming, costly, tedious work, I am sure you will agree, but required. Having out of date training materials can lead to confusion, errors and poor performance.
The big question is where do you look for information and answers when you either can’t remember or want to do something that you have never done before? Most people these days look on the internet, but the purpose and writing of the documentation remains the same. It is only how it is accessed that is different – instead of going to the library and seeking a specific book, you can now search for it online. In several organisations we have worked with on new software implementations, they have used software that can pick up where the user is in the process and supply a list of related ‘How to’ scripts. This was done with the aid of an E-learning scripting tool. The user then has to pick the most appropriate from the list and follow the steps.
There are different levels of documentation that serve different purposes for different audiences.
|Tutorials or Work Books||Learning-oriented||End User||Basic scenarios, examples, exercises for use during the course or as self-paced study|
|How To Guides, Job Aids, Quick Reference Guides (QRGs), Work Instructions||Goal-oriented||End User||Short, precise steps to solve a How do I..? question.|
|User Guide/Manual, Explanation||Understanding-oriented||End User||More detailed giving reasons why things need to be done in a certain way and explaining the full processes and procedures|
|Reference Manual, Functional Specification||Information-oriented||Developer and Trainer||A software project requirement and the source material for the trainer when developing the User Guide.|
|Lesson Plan||Process-oriented||Trainer||The course with its aim, objectives and running order of topics, with key references to other documentation and slides.|
|PowerPoint||Information-oriented||Trainer||Slides showing course outline, the big picture and key topics to be covered to get there. Use pictures, diagrams but use words sparingly on slides, expand on the detail with your voice rather than allowing them to read.|
What to do when you are a beginner. These are used at a training session or to support self-paced learning and contain basic information, examples and exercises. They provide sufficient information to allow the new user to grasp the steps that they are required to take. The examples and exercises are learning-oriented so that the user is able to apply the steps and see the results of the main topics. We all learn by doing, not reading, so if there is additional information or ways of doing those steps, provide links to a more detailed Explanation/User Guide. A Tutorial or Work Book is short and to the point of learning a new process and is not the place for detailed descriptions and alternatives. A Work Book is often classed as the Exercise booklet for a course. This is the start of the learning and simple steps that work, are easy to follow and are listed in a concise and logical manner. The user needs to see that what they do actually works, so make sure your examples are realistic and the exercises will work. This will be the building block for the user’s future learning of this product, so make it a positive one and give them the confidence to continue.
How To Guides, Job Aids, Quick Reference Guides, Work Instructions
What to do when you get stuck. These are written to solve a specific problem or situation – How do I…? They will be short and to the point of achieving the goal, and are therefore often considered as goal-oriented. The steps are the same as in a tutorial, but may assume some knowledge of the earlier parts of the process and are aimed at a user with some experience of the software. They will concentrate on one step in the learning objective of the process, such as how to complete a specific field or fields of information in a customer address. In short, they are there and available as a speedy answer for how to do something when you are stuck! The How To guides often contain links to the more substantial User Guide so that the user can understand the concept better or see additional information if they wish.
User Guide, Explanation
Why you need to do what you do. The User Guide is provided to show the detail of the process or steps to complete a task. It also provides the reasoning behind the introduction of the step(s), the business rules that need to be followed and the options that are also available, such as a why the customer address needs to be in a certain format in each field or perhaps a different approach to the step(s). The User Guide is understanding-oriented, so that the user gains knowledge of why they are doing something and can apply that knowledge to other scenarios in the future. A new user faced with a large user guide that covers all topics, with any variations that are possible plus the rationale, rules and business best-practices is bound to be overwhelmed. This is why both a tutorial or how-to guide can link to the appropriate section in a user guide, rather than repeat it.
Where all the detail comes from. The Reference guide has the technical and development angle at its heart and is the detail behind each field in a piece of software and how it links together, or the detailed description of the machinery and how to operate it. It is the functional or technical specification document and often does not reach the end user, but is the basis on which the user guide is created. It is information-oriented and although it does contain the basic steps to use or operation of the software or machinery, it is not the definitive guide that the end user needs because it focuses on the technical elements in bite-sized chunks and does not include the rationale for why certain things are as they are.
Consider the following:
- Content – topics, tasks and procedures in small steps, usually bulleted for ease of reading, be factual
- Audience – what is their current level of knowledge and ability, aim too high and you lose the new users, aim too low and the intermediate and advanced users will consider it beneath them to read it
- Use – is it for training sessions only or to be referred to after training has taken place, ie when performing the tasks on the job and additional help is required
When you start to write use the following guidelines:
- Write in plain English. Do not use technical terms, unless they are really necessary or currently part of the work place vocabulary and make sure they are also explained in simple language/terms for a new user.
- Use the full text for acronyms and abbreviations the first time they are used and include the shortened version in brackets, eg Quick Reference Guide (QRG). Include a Glossary at the end of the User Guide covering all acronyms and abbreviations.
- Use the active voice – It is concise and to the point and relevant when someone is looking up how to do something. Think Subject – Verb – Object. In the steps you describe, the subject is you (the end user) and is therefore often omitted. Think Click the Post Code field. Type the Post Code using the correct format for the Country shown in Appendix 1 The reference to the Appendix can be linked so that the user can refer to it if they do not know the correct formats.
- Be consistent in the use of terminology, tone and style of writing.
- Use short sentences and phrases as long ones can be confusing. Numbered steps are easier to follow than long paragraphs.
- Include illustrations (graphs, flow charts, tables, pictures, screen displays, examples of finished tasks) where appropriate to clarify concepts and enhance understanding. It also adds visual interest. Illustrations should be in proper proportion to nearby text.
- Include a table of contents that includes chapter headings as well as the next level of subheadings, so that the user can get to the right place quickly and easily.
- Consider using Appendices, a Glossary, an Index and a Bibliography/further reading as appropriate.
- Check spelling and grammar.
- Keep it up to date – certainly if there are upgrades, changes to processes and procedures and perhaps schedule a review every 6 months.
So what is it about training documentation that makes it good or bad? In our Technical Writing course we look at:
- What is it? – the qualities of good business writing
- Preparation – purpose, content, audience and collating data
- Structure – different ways of structuring the document depending on document type and purpose
- Document types – simple reports, procedural manuals, QRGs
- Layout and format – guidelines regarding fonts, attributes, colour, tables, pictures, etc
- Examples and samples to get you inspired
17 June 2019