2   Development Process

Researching and Writing

Writing the manual consists of gathering the required information and drafting the text.

Gathering Information

Information for your manual can come from other documents, from subject experts, from work flow analyses, or from your own knowledge or experience. The challenge is to get this information into a form you can use in your manual.

Examples of documents you might draw from include:

• previous manuals from within your organization
• manuals from other organizations
• vendor documentation, such as specifications or operating and maintenance instructions
• correspondence files
• training materials
• the acts and regulations the text must conform to
• files of complaints
• problems identified by other agencies

Look on the Internet for manuals belonging to other organizations that you can take ideas from. If you want to integrate part or all of their manual into yours, ask them for permission first. Using it without their permission violates their copyright. If you do use ideas found in other manuals, even in a minor way, you should cite the source in your acknowledgements section.

You can get information from subject experts either by interviewing them or by letting them prepare a rough draft that you can edit. While interviewing and drafting takes a little longer initially, it’s often more reliable, and may take you less time overall.

The people who will use the manual are often the best sources of information, and should be consulted and involved as much as possible. The success of the manual often rests with them, so you want them to feel a part of the result. When selecting subject experts, try to get a representative cross-section of users from different backgrounds, levels of experience, and geographical areas.

Interview Techniques

Here are some strategies to use when conducting interviews:

• Schedule interviews in advance, and tell subject experts what you want to discuss so they can prepare, if necessary.

• Do your own homework—don’t waste their time by asking questions about subjects that are already well documented elsewhere.

• Take on the role of novices—don’t be afraid to ask dumb questions—they are often the questions that novices need to have answered most.

Take brief notes when you’re interviewing. If you try to record every word they say, you won’t listen well, or you’ll slow down and lengthen the interviews. Instead, keep one- or two-word notes to remind you of important points. After the interview, go through your notes again and flesh them out. Some writers like to tape record their interviews to refer back to later. While this records verbatim what was said, it’s seldom necessary in manual writing, where the ideas, not the words used to express those ideas, are important. Tape recorders intimidate many people and are likely to make them less communicative.

Walk-Throughs

If you need to write instructions for operating or maintaining equipment, ask your subject expert to walk you through the steps using the equipment as it’s normally used, or to act out the process where it normally takes place. You’ll find the process easier to understand and write about, and it will remind the subject expert of important steps that might be overlooked if the procedure was being described in an office. Walk-throughs can also alert you to special problems users may face, such as too much noise to allow them to communicate easily among themselves to coordinate activities. If you can’t hear your subject expert, users won’t be able to hear each other.

Filing Systems

During the project, you will accumulate masses of paper. The best way to organize this information is by setting up a paper filing system that mirrors the structure of the manual. Prepare a file folder for each section of the manual, and group the files according to your chapter structure.

At the same time you can set up a folder structure for your word processor and other files. Like the paper filing system, it should mirror the structure of the manual. Make sure that these files are backed up regularly. Keep one copy of the files off-site.

Drafting Section by Section

Once you’ve gathered the information you need, you’re ready to start writing. To many people, writing the first draft is the hardest part, and many experience writer’s block. The best way to overcome writer’s block is to plan your document thoroughly. If you’ve got a good outline, you’ve already done this.

When you do start to write, don’t be too hard on yourself. Don’t try to write a perfect draft by editing at the same time. You’ll find you can’t do either effectively. Most writers write first, then come back later and review and revise it. If you can, let a day or two pass before coming back to revise. The passage of a little time will help you see problems that might not be evident immediately after drafting.

All writing should be done using the word processor template created when developing the prototype. It’s often best to have your writers simply write the text and not format or lay out the pages. This work requires expert-level word processing and should be done by the production specialist on your team, if you have one.

Don’t start at the beginning. The introduction is usually the hardest part to write, so start somewhere else. You can write the introduction later, once the sections are written. Similar to the way movies are filmed, most sections are not written in the order they appear in the manual.

Even if you’re following a detailed outline, you’ll find writing a lot easier if you continue to organize your thinking. Most writers will do a quick paragraph outline before getting started on a section. Just jot down the subjects you want to cover, then sequence them in the order they should appear. This helps ensure that you know where you’re going, and reduces the need for rewriting later.

Use your word processor’s spell checker once you’ve finished each section, but don’t rely on it to catch everything—it won’t find errors that masquerade as other words, such as there instead of their.

If your subject experts or others are drafting the text, make sure they have a copy of the prototype section, styleguide, and word processor template, and go through it with them carefully. Differences in level of detail, writing style, methods of organization, and ways of presenting information are the biggest problems when multiple writers are working on the same project.

Preparing Graphics

As you draft, consider the best ways to present information. Writing it out sentence after sentence, paragraph after paragraph is often not the most appropriate way of communicating information. Think about graphical ways of presenting information, such as illustrations, diagrams, tables, or bullet lists. For a description of the various ways of presenting information, see Chapter 6, Methods of Presentation.

Plan and create your graphics and illustrations as you write. Depending on their complexity, you can either create them yourself or have the production specialist prepare them for you. These graphic files should be integrated with your word processor files so the manual can be printed digitally and displayed online. It’s best to have the graphics in place, and the pages completed formatted, before sending the section out for review.