Creating easy to read guides for users is essential for all products to succeed. With any new product, some users are reluctant to change, but if the Technical Writer can provide an easy to read, friendly, and understandable user or training guide, less resistance would be encountered. The user cannot be expected to instinctively know how to operate and use a new product. Even if the product is an updated revised version of an application, the user still needs to know what is new and why it was revised when the existing version seemed fine and workable for them.
Before beginning to write the guide, communicate with and get to know what the users current knowledge is and how they prefer to have documents presented. This way you will know whether or not to use more visuals, charts, figures, etc. The Technical Writer needs to know how the audience learns best.
After meeting with the users and learning and understanding the functionality of the, e.g., application, the Technical Writer can now begin to write the User Guide. If the User Guide is about how to run an application, include:
- Table of Contents
- Information on the product; include a bit of history
- How to operate, install, log-on, use the program
- What prompts to expect, information required, error messages
- Getting help with an FAQ section if applicable
- Trouble-shooting section
- Glossary
- Appendix with samples if needed
- Feedback section
If it is a revamped application, with a new interface, menu, etc, then in addition to the above, include:
- Pictures of the old version versus the new so that a comparison is easily visible
- Information on new processes, i.e., how to add/remove data to/from the forms or how to reset headings for a report, or how to use the new print or search procedures
- Symbols or other markers denoting new items with details
To make the User Guide more appealing and to emphasize details, include visuals such as, graphics, process flow diagrams, charts, screen shots, or images. Also, use storyboard or animation tools to aid in displaying the flow of the application or the steps leading to its functionality. If it is a complicated application or a new process, consider creating a video or presenting an instructor-led class to illustrate and provide information. Sometimes a short one sheet reference guide is all that is needed.
Note: Sometimes there is a cross-over between User guides and Training Manuals. But there is a difference between them. A Training Manual is usually provided during instructor-led classes, where the instructor can demonstrate, e.g., certain tasks. The student can then use the manual to reinforce what was taught by working through a set of exercises. Solutions would be provided as well as explanations. A quiz would also be presented at the end of each chapter/section along with explanations to help guide the student during the learning process. But no matter which one is written, the content would also include items similar to the standard User Guide discussed here.
More information on Ready Reference Sheets will be described in the next post. If you have any questions, or feel I’ve left out information or wish more information on an item, please leave a comment.
Gail Zack Anderson, President of Applause, Inc., has nearly 20 years experience in training and coaching. She
provides individual presentation coaching, and leads effective presentation workshops and effective trainer workshops.
Theresa Pojuner is a Documentation Specialist with over 20 years of writing experience and is skilled in many areas of documentation, for example, Style Guides, Training Manuals and Test Cases, wth a specialty n Technical Writing and Procedures.