Writing the manual consists of gathering the required information and drafting the text.
Information for your manual can come from other documents, from subject experts, from work flow analyses, or from your own knowledge.
Examples of documents you might draw from include:
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.
Here are some strategies to use when conducting interviews:
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 edit. If you can, let a day or two pass before coming back to edit.
And 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 modules are written. Similar to the way movies are filmed, most modules 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 is called paragraph outlining, and helps ensure that you know where you’re going, and reduces the need for rewriting later.
If others are helping you draft, make sure they have a copy of the sample section, style guidelines and the word processing template. That way, their drafts should be similar to your own and need the least amount of editing later.
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. Also think about using 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 5.
Plan your graphics as you write. You can either create them yourself, or have a graphic artist or technical illustrator create them for you. It’s best to have all the graphics in place before you send the manual outfor review, especially if the graphics communicate important information.
Most writers like to format the text pages as they write because it shows them exactly what the pages will look like. Integrate the graphics together with the text, either by manually pasting them into the draft, or by integrating the graphics files with your word processor files. It’s best to format the manual before you circulate it for review.
Wait until the text chapters are written before preparing the table of contents, introduction and glossary. They’re easier to prepare later on in the project. Don’t prepare the index until the final review is complete and all required changes have been made—last minute changes can wreck havoc with an index.
