Documentation as a Training Tool
by Doris Loretta
Training can take on many different forms. Some of the best training comes in the form of good documentation or reference manuals. Whether it is for a software package or a business procedure, the documentation can often make or break a new initiative. Following some guidelines will help in creating this important document.
Know the audience. Are you writing a general user guide, a technical reference manual, a tutorial, or a quick reference job aid? The language and the amount of information will depend on the answer to that question.
Be careful of acronyms (abbreviations) and jargon (industry specific terms). Good trainers already know not to use too much jargon and acronyms in their training sessions. The same rule applies to written materials. If acronyms and jargon need to be used, do it sparingly, define them when first used, and include them in a glossary. Particularly with introductory levels, never make assumptions as to the audience’s knowledge of such terms. The higher the audience skills level the more acronyms and/or jargon is permissible.
Software documentation in particular has gotten a bad reputation largely due to acronyms and jargon. This documentation started out as a way to track programmers’ development of the software. It was written by programmers for programmers to document the software’s functions and features. When software usage became more commonplace, oftentimes this same documentation was passed on as a how-to document. With no definition of the acronyms or jargon, new software users were unable to use it as a reference tool. IDG publishers found success in their “Dummies” series with books that assumed its readers had no prior knowledge of the subject explaining all that jargon.
Be concise. People who need to use your documentation will not have time nor patience to read through expansive, flowery language. Explain the feature, function, or procedure without trying to impress the reader with your command of the English language. Using common words speeds the process of comprehension. For instance, it is easier to understand “zipper” rather than “an interlocking slide fastener”.
Illustrations are the best way to describe a procedure quickly. The old adage, “a picture is worth a thousand words” really is true here. If you would like to show how an operator should safely turn on a machine, take a digital picture of a real person doing it. If you want to describe where to click on the screen, capture it in a picture. A good tool to use for screen capture with mouse pointers is a small, economical program called SnagIt. (www.techsmith.com). Including these graphics into the documentation will allow easier comprehension.
All good manuals require a Table of Contents, a Glossary, and a good Index. With a good word processing program the process of adding both the Table of Contents and the Index is now automated. There is no longer a good excuse to omit them. Documentation not having these elements is of no value as a reference resource.
By following these guidelines, your documentation will be more useful to its audience. In creating well-organized, clear, and concise documentation, you will contribute to the success of your company’s new initiative.
Doris Loretta is co-owner of Paris Mountain Associates, Inc. in Greenville, SC. She is a certified Microsoft Office Master Instructor and has been in the training/education profession for over 20 years. She is the author and administrator of Tipsfromdoris.com.
 Article PDF
You may need the Adobe Acrobat Reader™ to view and print this document. You can download the FREE Reader at www.adobe.com.
Copyright 2008 Paris Mountain Associates, Inc.. All rights reserved. While you may copy this publication, its content may not be modified. You may, and are encouraged to, share the publication with others who may benefit from receiving it.
|
