Topic 12: Editing, proof-reading, reviewing & production

Editing & proof-reading

What to do after you've written the first draft.

Editing

The task of editing begins after the first draft is complete.

Print first draft

The first draft is generally entered into a wordprocessor and the result formatted and printed using either:

· The wordprocessor's own desktop publishing abilities.

· DTP

The choice depends on the standard in your organisation.

Bind

Once the first draft is formatted and printed, bind it. This is useful because:

· Organising the material makes editing easier.

· It gives you a preview of the finished product.

Edit first draft

Editing marks a turning point in your attitude towards the document. It calls for a shift from a subjective to an objective point of view. You need to shift your perspective from being the one who wrote it to the one who is now going to criticise it.

While nobody likes having their work criticised, being your own harshest critic raises the standard of your work above average and so helps to create a professional result.

Imagine you are the reader, then look for:

· Clarity

· Brevity

· Active voice, present tense.

· Sexist language.

· Illustrations & Examples Are there enough of both to support and clarify the information being presented?

Editing is time consuming when done properly.

Edit second draft

After making the changes arising out of the first edit, print and bind it in the same way as above. While the first edit looks for improvements to the language, format and content, the second edit looks for technical accuracy and consistency of presentation.

Ask yourself "Have I delivered what was promised?".

Spell/grammar check, TOC, index

After implementing the changes from the second edit, do a thorough spellcheck, and if you have it available, also a grammar check. Grammar checking programs allow for different kinds of writing (i.e. general, legal, business, technical etc.) Make sure you select the right category.

Also generate the table of contents and the index.

First proof

After doing the checks and generations mentioned above, print and bind the result. It is now ready to be proof-read.

Editing Checklist

· Acronyms. Uncommon acronyms written out first time they appear.

· Bulleted Lists. Correct indentation and consistent bullet size.

· File Names, Path Names, and Operator Entries. Consistent use of typeface.

· Headers and Footers. Section and chapter titles in headers/footers correct

· Headings. Proper and consistent capitalisation.

· Index. Check accuracy of all references by looking them up in the manual.

· Key Names. Consistent use of typeface and abbreviations (i.e., Ctrl for Control).

· Measurements. Make sure units of measurement are used consistently (i.e., all SI units followed by imperial units in parentheses).

· Numbered Lists. Check for correct numbering sequence; look for repeated, missing, or out of order numbers.

· Page Numbers. Make sure pages are in the correct order.

· References. Consistency of typeface and phrasing when referring to other publications and other parts of the manual. Check that references to page numbers, figures, and tables are correct.

· Spelling. Run your electronic spell checker AND check manually (neither method is accurate enough by itself ).

· Symbols. Make sure symbols are used consistently (i.e., if you use a symbol such as a square to mark the end of a numbered list, make sure it appears at the end of every list).

· Table of Contents. Make sure page number listings match page numbers in the manual.

· Word Choice. Make sure wording of instructions is consistent (i.e., do not use "choose" and "select" to mean the same thing; use one or the other).

Proof-reading

Proof-reading begins after the editing is complete. From a practical point of view, the manual is as finished as you can make it without being checked by a third party.

Who proof-reads?

Finding the right people to proof-read your almost complete manual is the final challenge to overcome. Print out four copies of the manual, place them in binders and write "Draft: dd/mm/yy. Copy No. n of 4" on the cover to identify it as a draft produced on a certain date and the copy number out of the total of four.

The process happens on these four levels:

· Accuracy - the information given in the manual is checked for technical accuracy. Spelling & Grammar - it's still advisable to have a literate person check.

· Usability - the manual is checked for usability by the same people who will use it.

· Says too much - the manual is checked for content which might inadvertently give offence or disclose information of a sensitive nature.

Reviewing and field testing

Getting useful feedback about the usefulness of the document from people who are qualified to comment.

Why do it? No-one, not even the most selfless among us, is completely ego-less when evaluating their own work. Since we don't want to find fault with our work, we tend to overlook faults when we see them.

Reviewing the manual

Selecting reviewers and when to review

Find several different people who can bring a different perspective to a document. That is unless you are lucky to have a person who can adopt multiple perspectives when reviewing a document.

The following perspectives need to be brought to bear:

· Technical perspective - checking for technical accuracy and completeness.

· Management perspective - how well the document achieves it's overall objectives, how well it projects a positive image

· Editorial perspective - checking for conformity with accepted writing conventions.

· User perspective - checking the document for it's "usability".

Show reviewers how to review

The reviewers need to be given specific guidelines on how to conduct an effective review. Unless people have had specific training in this field, they are unlikely to know how to do it properly, since it does not feature in school or university curriculums.

As a general rule, the quality and quantity of the reviews you receive are directly related to the amount of time and effort you spend spelling out what is needed from the reviewers.

One major problem which often occurs is that the reviewers confuse which perspective they should be using. The technical reviewer might slip into editorial perspective, while those looking from a management perspective can sometimes do the work of the technical reviewer.

· Is the purpose of the material clear and accurate?

· Is the definition of the audience's needs and experience complete and accurate?

· Do the graphics suit the audience?

· Has all required information been provided?

For each review type (technical, management etc.) a separate checklist in addition to the one above should be included. For example, with the management review:

· Does the information show accurately the benefits of the system?

· Can all promises made in the document be kept?

· Does the material protect the confidentiality of our organisation proprietary information?

As a final courtesy, when the document has been finalised, send a copy to each of the reviewers with your compliments and thanks.

Give feedback to reviewers

Regardless of how much time and effort a reviewer has spent, they should all be given feedback. Let each know the changes that will or won't be made based on their review comments. Feedback will increase the chances that the person will agree to review other documents in the future.

Production

Paper size & weight

Size User manuals should be printed on white A4 paper, preferably on both sides. Weight Pages should be copied or printed on 110 gsm paper.

A blank buffer sheet of 150 gsm paper can be used as the first and last page of the user reference guide. This prevents the photocopied pages adhering to the plastic covers of the binders.

Print quality

The master copy of the document should be printed on at least a 300 dpi, preferably 600 dpi laser printer. The master should be checked for degree of blackness, smudging, and paper quality. It is imperative the master is of sufficiently high quality to copy successfully.

Binding

Documents should be bound in comb-binders or loose leaf four ring binders.

Document release

Approved or unapproved documents are released to project team members and others on a need-to-have basis. In other words you issue as many as necessary, but no more. The more documents issued, the harder it is to control them with regard to making sure everyone gets updates.

Version control & re-issue of documents

Documents which are subject to version control, and which are issued as controlled hard copy, should be issued in one of two ways.

· The total document is re-issued each time a new version is produced. Recipient disposes of the earlier version

· Only updated pages are re-issued. Requires the maintenance of version control at the page level, and the recipient should remove and replace the revised pages. More difficult this way.

The choice of method depends on the type and size of the document, and the frequency of issue of new versions.

Controlled distribution documents

In rare cases, a document will contain secret and/or highly sensitive information.

· Where the document has "controlled" hard copies, those people/positions who are in receipt of a "controlled" copy should be known by means of a register.

· Where a new version of a document is distributed, a notice should accompany it to the relevant staff which identifies the reason for the change and the procedure for them to update their existing copy.

· The new version and the notice need go only to the holders of "controlled" copies.