The User Guide and the Training Manual: Learn to Write Both

By Cathrine Whitaker, Member, San Diego Chapter

Have you had this experience? Your boss says to you, "Now that you have finished the user guide, can you start writing a training manual?" You confidently say, "Sure, I'll start it right now." Then you walk away wondering how you are going to do it.

In this challenging time of job insecurity, a great career strategy is to know how to write both user guides and training manuals. I currently work as an instructional designer for Macromedia, Inc., and have more than 20 years of experience as a technical communicator. I have also worked as a technical writer, training analyst, and professional instructor. I want to share with you how to transfer your writing skills and product knowledge from one writing format to another successfully.

Basic Similarities

There are many similarities between technical writers and instructional designers. Both types of professional writers must first analyze their audience's skill level, plan their project with a detailed time schedule, determine the end product (user guide, installation guide, or training manual), develop the content, test the system, make final edits, deliver the end product, and then evaluate feedback from customers.

Basic Differences

The major differences are the documentation process and the end products. Technical writers document the user interface of an application. They document all the features and functionality for a particular software system.

Technical writers usually work in small chunks of content. They document the step-by-step procedures for completing a specific task. Their focus is to enable the user to know how to use the system. The technical writer will not know where the user has entered the online help system or user guide, so information may need to be repeated. If there are last-minute changes in the software, they may only have to change one topic, or they may need to conduct a search and replace operation to change content in related topics.

Instructional designers must document not only how the system works but must also document why to use a particular feature and when to use it. Instructional designers must focus on teaching the student to use the software application by documenting best practices and providing examples.

Instructional design documents (training manuals) are designed and developed in a structured, logical, and linear sequence. Instructional designers use a scenario-based approach to explain how one system function affects another. There is a logical flow of events and students learn when and why to use system features. The students learn a workflow process, so they can see the big picture of how the system works.

If there are last-minute changes in the software, the instructional designer may have to rework several lessons to document how the new system change has affected other lessons.

A practical approach to instructional design:

Tell students what they will learn in a specific lesson.
Teach students system features and functions that support the lesson's objectives.
Remind students what they have learned through hands-on practices.

User Guides and the Technical Writer

The purpose of a software application user guide is to provide helpful references to specific system functions. This will help the user to find the information they need quickly and easily and get right back to work. A common user guide is the "Getting Started Guide" that is developed to help the user get comfortable using the software. A user guide should cover how to run the system, how to enter data, how to modify data, and how to save and print reports. This guide should also include a list of error messages and advice on what to do if something goes wrong.

An effective way to write a user guide is to create all the content in an online help system, such as RoboHelp, and then create the user guide through the printed documentation feature. Single sourcing is the act of writing the content once and using it in many formats. This way, you have created the online help system for the computer application along with a user guide for your end users.

The writer of a user guide should have a good working relationship with the product development team. Usually, the technical writer works directly with the developers and documents the step-by-step instructions on how to perform a system function. Technical writers design, write, and organize documents to deliver clear and consistent technical information. Well-written technical information can reduce human error, ease transition to a new system process, and reduce training and support costs.

In the planning phase, the technical writer creates a detailed outline of the system topics, starting with the introduction and advancing to complex features:

Introduction of the system
"Getting started" tasks
Developing the system
Modifying the system
Customizing the system with advanced features
Conclusion

Technical writers work closely with developers to write, test, rewrite, and retest the system features until they have a good draft for review. The next step is to submit the user guide for editorial review. At the same time, the quality assurance engineer should review the user guide for technical accuracy. Before publication, it is a good idea to double-check with the developers for last-minute system updates. After all the last-minute edits have been made, then the technical writer can send the user guide to the printer.

Training Manuals and the Instructional Designer

In writing this article, I assumed that most readers would be technical writers, so I purposely spent more time introducing instructional design concepts. Having product knowledge of half of the challenge in writing training materials. Once you know the system, you can then focus on clearly introducing those concepts to new users and reinforcing that knowledge in a comfortable and productive training environment.

Another essential aspect of instructional design is to engage the student by developing hands-on practices and independent labs. This enables the students to practice the system features they have just learned before they move on to the next lesson. Instructional designers may also be asked to develop a written or performance test so managers will know how their employees did in the class.

The purpose of a training manual is for the instructor to teach participants how to use specific system functions. You may want to use the Instructional Systems Development (ISD) process, which is a systematic method for developing instructional materials, presenting the materials in a logical sequence and evaluating the outcome of the instruction.

The benefits of using the ISD model are:

Scientific — The designer determines the audience needs and teaches those specific skills.
Systematic — Each step builds on the previous step, which avoids redundant instruction.
Formative — Evaluation occurs after each step.
Cyclic — The model can be applied to existing instruction and ensures effectiveness of instruction.
Cost-effective — Trained people are more productive.

It is important to create a project plan so you can deliver a high-quality product within your allotted time frame. Most instructional designers use the ADDIE systematic approach for developing their training manuals:

Analyze
Design
Develop
Implement
Evaluate

First, the instructional designer analyzes his or her audience to determine:

If there is a need for training.
How to tailor the instruction to a specific audience (new or experienced users).
The prior system knowledge level of their audience.
Their goals and objectives: What is the intended outcome of the instruction?

In the design phase, the instructional designer develops objectives and determines the type of media for the training materials.

An objective is a statement of student performance that is measurable. An objective contains a behavior, a condition, and standards, such as "The student will be able to record a Captivate movie with 20 slides without using the online help system."

A behavior is a performance that be seen or demonstrated, such as define or list. A condition states items that are specifically granted or denied the student when performing the behavior, such as "without referring to the textbook." A standard is the criterion for completing the objective, which relates to accuracy, time/speed, adheres to procedure, of quality specification.

The instructional designer must determine the type of media that will be used to deliver the training materials, such as instructor-led, self-paced, computer-based, or hands-on practices; independent labs, books, job aids, slides, videotape, or film. The designer must also determine if tests will be written or performed on a computer.

In the development phase, the instructional designer gathers resources, creates the content, and applies the media. He or she creates the content by dividing the instruction into discrete sections. This is called "chunking" information by topics, lessons, modules, or courses.

Some helpful tips for development are:

Present general concepts first to provide a frame of reference. Then move to more complex topics.
Use the KISS principle; keep it sweet and simple. Too much information can be overwhelming, so present one concept at a time.
Be consistent with the instructional design so students can follow a set pattern.

Then the instruction is put into the selected medium or media:

Written manuals
Films, videos, or CDs
Tutorials, demonstrations, or interactive simulations

Implementation occurs when the instructional designer places the instruction into the actual training environment. Implementation can also be used as an evaluation tool by conducting a test class and receiving feedback from instructors and students. They the training materials can be fine-tuned before being sent for production.

During the evaluation phase, the instructional designer looks for:

Consistency of instruction
Relevance of instruction
Effectiveness of instruction

Now that you have read this article, I hope you have gained a sense of comfort and confidence that you can easily transfer your writing skills and product knowledge from one writing format to another.

Cathrine Whitaker's article originally appeared in Signature, the newsletter of STC's San Diego Chapter.

Rough Draft Home | Phoenix Chapter Home | STC Home | Send Us Feedback | Archives

Technical Writing in the Financial Industry, Part 1
Who Are We? 2005 Phoenix Chapter Survey Highlights