2   Development Process

Editing and Reviewing

Reviewing with the Subject Expert

Once you’ve drafted a section, send a copy to the subject expert for review. This is usually an informal review immediately after you’ve finished writing, but before editing. Ask the subject expert to look for the following:

• missing information
• unnecessary information
• technical accuracy
• appropriate organization

Make it clear that you are not interested at this time in typos or other issues. The content and organization may change significantly, so time spent fine-tuning will likely be wasted. You may need to go back and forth several times until both you and the subject expert are happy with the draft section.

Editing Draft Sections

The initial edit (sometimes called a substantive edit) is done after the first draft of each section is completed and has been reviewed by the subject expert and revised, but before the first technical review with the project team. Don’t wait until you have a first draft of the full manual—you can edit each section as it becomes available.

The editor should carefully review each section, looking for the following:

• completeness and accuracy
• appropriate organization
• logic and coherence
• general writing style
• general conformance with the prototype section, styleguide, and style sheet

While the editor should mark any evident problems, the focus during the initial edit are issues of content, organization, and general writing style. Since the technical review will probably result in significant changes to the text, correcting problems with spelling, grammar, punctuation, usage, formatting, and typographics is less important and can be left to the final edit.

The editor should read each section at least twice: once for familiarity with the content, and a second time to identify and mark problems.

If you don’t have a professional editor on your team, your best writer should serve as the editor. Or consider contracting the services of a professional editor. If possible, writers should not edit their own writing—we are all blind to our own errors.

The edit should not be done solely on the screen—some problems are easier to spot on paper where you can see more of the text. While it may be faster, most editors find it easier, and make fewer mistakes, when they edit a printed copy.

Following the initial edit of the first section written by each writer, the editor and writer should review the draft together and go over the changes. This helps the writer understand the reasons behind the changes, and later drafts of new sections should require fewer changes.

With subsequent sections, the editor can simply send the editorial changes and comments back to the writer for incorporation. Alternatively, the editor can make the changes directly to the word processor file, and forward the marked-up copy and the revised copy to the writer. What’s important is that writers have a chance to review the editorial changes to make sure the editor hasn’t inadvertently changed the meaning, and to get feedback on their writing so that subsequent drafts will need less editing.

Where possible, the editor should pencil in the word changes recommended. Simply writing “this paragraph needs work” is not as useful as an edited paragraph ready for insertion.

Reviewing with the Project Team

Once you and the subject expert are happy with the section, make copies and circulate them to the reviewers designated in your document plan. The review can be done section by section or chapter by chapter. Don’t wait until the whole manual is written before scheduling the technical review — the task of reviewing the draft will be so onerous that few will review it thoroughly.

Instead of sending out review copies, you can schedule a walk-through with the reviewers. Book a conference room and take the reviewers through each section, paragraph by paragraph. It’s more time consuming, and in busy organizations it can be difficult scheduling meetings for large groups of people, but the review will be more thorough and differences can be discussed and resolved on the spot.

Be wary of new reviewers added at the last moment. If they haven’t reviewed the document plan, they won’t have enough background on the project to review the draft intelligently. For example, they may have different notions of the purpose of the manual and who it’s for, and may suggest changes that are inappropriate. You can waste a lot of time answering their questions with information provided in the document plan. Make sure new reviewers get a copy of the document plan before they begin reviewing.

Use a cover letter on review drafts explaining to reviewers what you would like them to look for. You can request that different reviewers review different parts. Tell them not to spend time looking for typos, spelling, and grammatical errors — that the section will be edited again after the review changes have been made. Otherwise, you may have your subject experts and other people spending valuable time on activities that will be duplicated later, and usually done better.

Give reviewers a reasonable amount of time to return their comments. One or two weeks is usually enough. If the schedule is tight, it may be less. You can ask that marked up copies be returned by mail, or that reviewers attend a meeting where the final changes will be agreed on.

Consider the suggested changes in consultation with the subject expert. The approved changes should be transferred onto a single copy of the draft. This will provide a clear record of which changes have been made. Keep this marked-up copy in the file for those interested in seeing the changes from the last review. Make the changes to the word processor file, then proofread the revised draft against the marked-up copy.

If you’ve done a good job with your subject experts, you shouldn’t have to make major changes from this review, but reviewers will often point out things that you’ve forgotten or perhaps ways of doing something better. If the changes to the section are significant, you should repeat the technical review and show them the revised draft.

Don’t be tempted to provide access to the word processor files to your reviewers and allow them to make the changes themselves. While this can save you the time of making the changes yourself, you’ll have no record of what changes were made, and you may have conflicting changes.

Testing Sections

It’s important that those who will actually use the manual test it for usability, completeness, and accuracy. With software documentation, you may want to test the manual at the same time the software is being tested. Try to allow sufficient time for this process to uncover any problems before the manual goes to print. Involving the users in testing furthers their sense of ownership of the manual, and increases the likelihood that they will use it when it’s finished.

If the actual users of the manual aren’t available, have some of your co-workers who are typical of real users test it. Of course, some manuals, such as policy manuals, can’t be tested easily in this manner.

Manuals are often tested as part of the technical review. To make sure that the required testing is done, allocate responsibility for testing different parts of the manual. For example, if you have a procedure for operating a piece of equipment, have a typical user of the equipment try to operate the machinery using the procedure you’ve written. Have the test conducted under the same conditions real users would experience. It’s amazing how many times these types of tests will uncover problems.

If your manual includes instructions that, if used incorrectly, could result in injury or death, or could result in significant damage to equipment or loss of data, you must test the procedures thoroughly.

Editing Final Sections

The final edit, or copy edit, of each section should be done following the technical review and testing of the section, but before the final review of the completed manual.

The copy edit focuses on:

• style and grammar
• spelling
• punctuation
• usage
• formatting
• typographics

Since each section will already have had an initial edit, few problems with contents, organization, or style should remain. Those that do remain should be picked up during this edit.

Since the final edit is focused on a broader range of concerns, the text may have to be read several times. Don’t try to look for everything during one pass. Read it once looking for problems with style, grammar, spelling, punctuation, and usage. Then go through it again looking for problems with page layout, headers and footers, and typographics. You may want to break it down even further, with separate passes looking at different things. For example, you may want to go through once looking at only headers and footers. Many editors like to prepare a checklist for each type of edit to ensure that they don’t forget something.

The editor should have a sound reason for every change. In English, the same thing can be stated in many ways. The editor should not simply change the text to the way the editor would have expressed it. The styleguide and style sheet should be referred to frequently while editing and used to decide if a change is necessary.

The editor should point out the good parts of the writing too. Editorial comments are often taken personally as criticisms, so they should be balanced.

Checking the Manual

Once all the sections have been written and edited, including all of the front and back sections (except the index), give the manual a final check. The initial and final edits were done section by section—this is your first and last check of the whole manual together.

Check that:

• all sections are complete, including the front and back sections (except the index), and are in the correct order
• sections are consistent with each other
• table of contents entries and cross-references are accurate

Any changes or revisions to the manual from the final check must be proofread since the manual will not be reviewed again. The person making the changes to the word processor file should do the proof- reading. To proofread, print a copy of each revised section and carefully check the new page against the marked-up page to make sure that all the changes have been made and errors haven’t been introduced.

Reviewing the Final Manual with the Project Team

Once all of the sections of the manual have been completed, reviewed, and edited, and the final check completed, it’s time for the final review. The final review gives reviewers a chance to see the whole manual as it will appear in print. Some problems, such as gaps in content, may only become apparent when all of the sections are viewed together. Since reviewers will receive the entire draft manual, don’t expect them to review it line by line.

Suggested changes should be considered by the writer in consultation with the subject expert. Approved changes should be transferred onto a single review copy, which is then used to make changes to the word processor file. Proofread the revised pages against the marked-up copy.

Getting Approval to Print

Before it can be printed or converted online, the manual should be approved and signed off. This is always done after the final review and is usually based on evidence that all of the suggested changes have been addressed and outstanding issues resolved. Depending on your organizational structure, however, this approval may require one additional review, perhaps by senior management, head office, or your board of directors.

Some organizations place an authorizing signature on each section. This isn’t recommended since some people seem to feel that the policy may be invalid if the person who authorized it vacates the position. Instead, include at the front a cover letter or other communication from the issuing authority formally authorizing the release of the manual.