What's the Secret to Creating Good Manuals and Handbooks

Team 6 - Kathy Owens

The secret is summed up by answering these two questions:

1. Can readers find what they're looking for fast and logically?
2. Will the book be easy to handle and hold up to daily wear and tear?

Users want easy access, physical convenience, and usability.

Seven (7) design elements - collectively referred to as front matter and back matter.

1. Table of contents - critical first impression to your readers and a negative one will discourage readers from reading it at all. Do the table of contents last, not first.
2. List of illustrations - Used for tables, photographs, graphics, etc. and appears right after the table of contents.
3. List of forms - Just like list of instructions and list of illustrations, but is just for forms. Most readers dislike forms. Having them in a list discourages the excuse, "I couldn't find it."
4. Introduction - Sets the stage for what's in the manual, such as purpose and scope. Helpful for all manuals, but keep it brief.
5. Glossary - List of special words, acronyms, abbreviations, jargon and terminology a reader needs to know. Kept at front or back of book. Keep it brief
6. Appendix - Info that supplements the text. Place it at end of section or at end of policy/procedure to which it applies. Traditionally, goes at end of book but readers hate to flip pages and may be overlooked altogether, so carefully consider placement.
7. Index - Most valuable "speed tool" of an alphabetical list of items in the manual. Many types of indexes. No matter what type, use terminology readers use. Indexes are back matter, but placement in manual can vary.

Six (6) Production Elements:

Main items to consider:

• How readers will use the manual
• Under what conditions will they use it
• How frequently they will use it

1. Size - standard dimensions are 8 1/2 x 11. Don't be bound by that but consider ramifications of larger or smaller manuals. Smaller manuals may get lost in the shelves with other books.
2. Paper - Heavy use of manuals might call for heavier pound paper, like 24-32. Location of use might call for laminated or plastic coated paper. Think of how and where they are used and plan accordingly.
3. Color - White is good, but don't be afraid to experiment, like colored paper for important pages, or for the table of contents or index. Don't forget that binder - if all the binders are black, pick red.
4. Binders - 3-ring are best if you are going to change the manual a lot. Spiral bound is good if you don't. Whatever you use, being able to open the manual flat is good. And, buy as good as budget allows. Cheap ones break. If you get them too big and it takes two hands to pull it from the shelf, it is not as likely to be used as one you can grab with one hand.
5. Cover - Popular are the binders with a clear, plastic envelope on the front. Don't forget an insert for the spine.
6. Dividers - One of the main 'speed tools' for accessing a manual. Make sure those are quality ones as well.

Distribution Issues - Develop a distribution list and get a signed receipt of acknowledgement from the person receiving the manual.

The psychology of the user:

• Big is daunting. Any document that needs to be carried with two hands is a candidate for the least-used.
• Most users reach for a handbook when they need an answer immediately (and easily).
• A good first impression (in the table of contents) will entice your users to read further.
• Most readers dislike forms and will find any excuse NOT to use them.
• People hate to flip pages. Placement is critical.
• A good manual has the good news first, bad news second, neutral news last.
• Users find illustrations convenient.
• Users like lists or tables of illustrations.
• Users like lists of forms; If you have a lot, you could even put them in a separate manual.
• Forms - they don't like using them, and don't like filling them out. Make them easy to find.
• Readers love a good index.

Chapter 7 Barker - Getting Useful Reviews

Team 7 - Jaeger/Lopez

To review documentation, you send it out to get the reactions of other people who are involved in the project.
Reviewing may take the most time compared to all other activities associated with document production.
Getting the most out of your review cycles - follow these 6 steps:

1.) Review the Document Objectives from the Documentation Plan
- Consider the documents objectives in the planing stage
- If applicable, make sure it meets company policy and reflects well on the company

2.) Determine the Type of Review Needed
- The kinds of reviews you design will depend, in part,m on the kinds of persons who have a stake in the documentation.
- Reviews offer challenges and problems, because not all of the persons whom you need to do the reviewing may be at your job, or may lack familiarity with your project.

3.) Establish a Review Schedule
- Make sure you give your reviewers enough time to fit the reading into their schedules.
- Careful reviews take approximately 1 hour per 15-20 pages.
- Sequential Circulation involves making only one copy of the document and then passes it to the next person to review it. Main advantage is minimal cost
- Simultaneous Circulation involves making a copy for all of the reviewers and receiving every ones review back. Main disadvantage is its expensive to create all the documents but you can tailor to diverse reviewers.

4.) Plan the Reviews
- A well-articulated review plan encourages you to think the process through by making it a goal-driven process.
- A plan provide3s background material to help reviewers respond more productively.

5.) Write a Cover Letter with Questions for the Reviewers
- To get relevant information out of your reviewers you should provide them with a cover sheet specifying what exactly you want them to pay attention to.
- Tell the reviewers exactly what you want them to do.

6.) Prepare Feedback Materials for Reviewers
- Reviewers need to know that you have read their comments and paid attention to them. Let each person know the effect of his or her work on your project.
- Use memos or thank-you letters for giving feedback to your reviewers

Reviewing Differs from Testing
Testing tends to concentrate on users and issues of accuracy and statistics. Reviews develop information about conformance of a product to management schedule and company policy. Also, reviews don't produce quantitative data about a document or statistics.

Reviewing Differs from Editing
Editors bring their training in editing. Reviewers such as managers, subject-matter experts, and programmers bring their professional opinions.

The Purpose of Reviews
Communication function - help communicate with people associated with your project
Management function - help you manage your project
Quality assurance function - help you maintain the quality of your product.

Reviewing Throughout the Documentation Process
Planning and Design Stage - your documentation plan should undergo thorough testing and review by managers, clients, and users
User Analysis Stage - an audience analysis should be presented to your managers, clients and users as a way of checking their validity and accuracy.
Development and Writing Stage - early in the development process you should validate the accuracy of your task list.
Draft Stage - you may want to schedule and implement draft reviews of parts of the document that have reached completion.

Reviewers as Partners
Tell them the benefits of participation - Make your reviewers understand that not only you benefit from them reading your document, but they also benefit.
Don't abuse the privilege - Don't overuse a good reviewer.
Show them revisions - Share your revisions. If you managed to get good feedback from reviewers, let them know how you used it.
Hold review meetings or walkthroughs - Have reviewers meet each other.
Keep contact over time - Keep a file of information about the work they have done which will help you avoid overusing them.
Return the favor - Don't compensate them. It's good business practice these courtesies in a meaningful way.
Thank them in print - When you have the opportunity, list the name of those who reviewed for you.

Negotiate Changes Diplomatically
Be firm only when necessary - The more you respect another culture's tendency to leave things undecided, the better chance you have of discovering a solution in the future.
refer to the Relationships Rather Than to the Person - Reinforce relationships when dealing with cultural conflict.
Acknowledge Cultural Differences and Give them Value - Engineers come from a "high context" culture where writers come from a "low context" culture. Compromise between the two.

Do a User Walkthrough
This is where you present the document form end to end and focus on the key issues of usability.
How to Set Up a User Walkthrough
1.) Decide on the issues you want to examine.
2.) Choose the attendees.
3.) Prepare a meeting agenda.
4.) Make copies and provide files for all attendees.
5.) Run through the walkthrough. Begin by announcing the agenda.
6.) Do a follow-up review. Send copies with the suggested changes to users after the meeting.

User walkthroughs offers a number of advantages for writers and users. Users can have a say in the development of the documentation and allows you to gain valuable insight into the usability of your document.