2   Development Process

Preparing Specifications for the Manual

The next step is to prepare specifications for the manual. This is the equivalent of the architect’s set of blueprints. The specification defines the contents, organization, and design of the manual, and how it will be produced and distributed. If done well, it gives everyone a clear picture of what the manual will contain and look like before you actually write it.

Preparing an Outline

The first part of the specification is the outline. The outline lists the chapters, sections, and topics that will be covered, in the order you will present them. Start with the chapters. Once you’re happy with the list of chapters, list the sections in each chapter. As you juggle sections around, don’t be afraid to rethink the chapters. Some may need to be split or merged. Once you’re happy with the chapters and sections, identify the topics to be covered in each section. Either list the topics in bullet form or describe them in a short paragraph. If you know you’ll want to include certain forms or create an illustration, list these too.

A good way of identifying potential topics for your manual, particularly for policy manuals, is to look at manuals developed by other organizations. Many organizations have placed their manuals on their Internet site. Try searching on the general topic of your manual and see what you can find. If you don’t find what you’re looking for using one search engine, try another. See if the topics they’ve covered would be appropriate for your manual. Use their manual to stimulate your thinking—don’t incorporate part or all of their manual into yours. Not only would this violate their copyright, but seldom is information developed by other organizations appropriate for your organization without substantial changes.

Don’t forget to list the title page, table of contents, index, introduction, glossary, appendixes, and other sections at the front and back of the manual.

Here are some types of information you may not want to include in your manual:

• information that is already in other manuals
• parts of acts, regulations, or collective agreements that are published elsewhere and may change
• information such as personal names and contact information that is likely to change (if you need to include them, put them in one place—don’t spread them throughout the manual)
• any information of marginal use to your audience

Developing an outline requires that you identify not just the contents, but how the contents will be organized. Draft the outline in the order the contents will be found in the manual, like you would for a table of contents (see Figure 2-2). Based on the needs analysis, you should know when and how the information will be used, and therefore what order it should be presented in.

The way in which you organize information often relates to the type of manual you’re developing. For instance, reference manuals, which are for experienced users, are sometimes organized alphabetically by keyword. User manuals, on the other hand, which are for novices, are usually organized topically in top-down sequence. For more information on organizing principles, see Organizing Information.

Since you are creating a revisable manual, you’ll need to identify the modules of the manual as you plan. The modules will either be entire chapters, sections, or sometimes for very large and complex manuals, sub-sections. See Dividing the Manual into Modules for more information on organizing and modularizing the manual.

Of course, as you write the manual, the outline will probably change a bit. Some sections may need to be split or merged with others. Sometimes chapter titles may change. The outline is simply your working table of contents.

Figure 2-2: Sample outline and progress report for a policy and procedure manual (first page only)

Estimating the Number of Pages

Once you’ve finished the outline, go back and estimate the number of pages in each section. Count forms and other appendix materials, which are simply added to the manual with very little effort, separately from text pages, which will require more effort. The number of pages is one of the main ways that writers estimate the number of hours needed to complete the manual.

Mapping an Online Manual

If you are planning an online manual, you’ll want to map its structure, which is similar to outlining the structure of a print manual. A key difference between print and online manuals is that while print manuals typically have a hierarchical structure, online manuals can have a web-like structure. Information can be arrayed in a variety of ways. Since you can link any topic to any other topic, the possible paths through the manual are endless—hence the appropriateness of the term web.

Mapping is simply planning out the various topics that will be available on the system and the network of links that connect them together. You can plan your online manual using a traditional outline, a story board with index cards, or yellow adhesive notes, or you can simply draw a map.

Figure 2-3: Sample map showing planned topics and links

If you want both print and online versions of the manual, consider how similar or different the structures will be. As you plan the print manual, imagine how it will appear online.

Preparing Style Guidelines and a Style Sheet

The document plan should set out the intended writing style of your manual. Some manuals are formal, while others are casual. Describe the planned writing style and make sure everyone is happy with it before you start writing.

Many organizations adopt a published styleguide and use it to guide the writing of their manuals. A good styleguide covers virtually every aspect of planning, writing, and producing a publication. If you are using Writing Revisable Manuals to guide the development of your manual, state that in your document plan. The Writing Styleguide sets out a wide variety of writing and usage rules to follow, and is organized alphabetically for quick reference. Other styleguides are listed in Bibliography on Writing Manuals.

As well as a styleguide, create a style sheet to record decisions on spelling, capitalization, hyphenation, and usage that are specific to your organization, industry, or technology, or that are simply not covered in the styleguide. Things like whether “vice president” should be hyphenated or not, or whether you will use “appendices” or “appendixes.” A style sheet is usually just a sheet of paper pinned to a bulletin board and added to as issues are encountered and decisions made.

Organizations that write a lot of manuals often develop their own internal styleguide to help ensure that their manuals are written and produced to a consistent standard. In-house styleguides are particularly useful if you want to establish standards for manuals across the whole organization. If you would like to develop a styleguide for your organization’s internal use, you can modify the Writing Styleguide.

Preparing a Sample Section

Nothing better demonstrates to others what your manual will be like than a sample section or prototype. Until they see a section or two completed, they won’t have a clear picture of your writing style, how you intend to present information, or the level of detail.

Five to ten pages is usually enough. Make sure the sample is accurate, well edited, and presented exactly as it would appear in the finished manual. Try to include samples of all the different ways you intend to present information. For example, if you plan to write a policy and procedure manual with some playscript procedures and an occasional decision tree, make sure you include a sample policy on a timely topic, a step-by-step procedure, a playscript procedure, and a decision tree.

With this publication we’ve included a template that you can use for your manual if you don’t have a standard design already established. Templates are provided for different versions of WordPerfect and Microsoft Word. Modify the template for your organization and manual by incorporating your logo, organization name, and the title of the manual in the headers and footers, and make other changes to customize it. Instructions for using the template are provided in Using the Manual Templates.

Prototyping the Online Manual

If you’re planning an online manual, prepare a working prototype that people can try. Make sure that enough of it functions to show what the final version will be like. It should include as a minimum:

• the design of the home page, including all graphics, banners, icons, and buttons that will be used
• the frame setup (frames are separate scrollable windows in which pages can be displayed)
• the main table of contents menu listing the chapters
• menus for each chapter
• index and search features (although they don’t have to be functioning)
• several information topics (such as policies)
• examples of tables, playscript procedures, flow diagrams, and all other methods of presenting information that will be used

Develop the prototype using the authoring tool you have selected (for information on selecting an authoring tool, see Chapter 8, Writing and Production Software). This will test its capabilities and limitations and give you a chance to work out the bugs. And time spent setting up templates and customizing features will not be wasted. The prototype should be placed in a test environment on your server to allow others to view it from their work station using their Web browser. As the prototype is refined and finalized, continue to update the version in the test environment so that everyone can try out the most current version.

Reviewing and Revising

Now that you’ve specified the manual, review the outline, page estimate, intended writing style, and prototype with team members. Before you finalize your work plan, make sure everyone agrees with the specification.