In this chapter, Barker discusses the steps for editing and fine-tuning software documentation. He writes that these guidelines help develop good editing attitudes and adapt the types of editing to the needs of a project. Also, they offer practical tips, rather than a specific sequence.
Establish Project GuidelinesThe first guideline Barker discusses is establishing project guidelines. Each project is going to differ from all others, so you should make sure you and your writers and other editors understand the roles and the goals of the editing process. Barker notes that depending on your organization, you may find yourself in one of the following situations: writer and editor’s roles combined, writer submitting to an editor, or editor of the work of another writer. Once you have an idea of your editing role, you can identify the objectives of your project. Barker provides some examples of editing goals, including: consistency in how the user perceives or experiences the document, consistency in the purposes of the information in the documents, applicability to multi cultural or cross cultural readers, correspondence of tasks and activities in a manual or help system, and smooth interaction among editors and writers.
Understand the Types of EditingThe next guideline Barker discusses is understanding the types of editing. He writes that there are four types of edits that roughly correspond to the stages in the writing process. These four types are managerial, substantive, copy editing, and proofreading.
Barker writes that managerial editing concerns itself with the documents and their planning and production rather than their actual format and content. This type of edit requires involvement during the entire documentation process because you are tracking and coordinating all the production processes, and the relationships with the other documents. In the managerial editing process, the document and design plans are looked at for consistency and accuracy. This is also where the style is set for the entire project.
Substantive editing involves editing language and information. In this kind of editing, you work very closely with the author to address the overall organization and structure of a document. Barker writes that the following are things you look for in a substantive edit: overall organization of the document, fluency of one sentence to another, parallelism in steps and lists, proper use of description, clarifying definitions, elements in right order, divisions of information are logical and consistent, maintaining correct emphasis on certain elements, minimizing redundancy and repetition, omitting irrelevant or inappropriate material, and finding instances of missing information.
Next, Barker writes that copy editing concerns itself with editing for grammar, mechanical style, and format. In this type of editing, you pay attention to all the surface-level elements of the words, sentences, paragraphs, pages and books. Barker also notes that copy editing is done on documents that writers have already tested and subjected to user and other reviews, and that this kind of edit doesn’t necessarily assume that you know a great deal about the reader of a specific document. The following are some of the things you look for when copy editing: spelling, subject/verb agreement, sentence fragments, incomprehensible statements, suitability of screen shots, typography, correct style, header and footers, margins, spacing rules, mechanics and punctuation, word compounding, form and use of acronyms and abbreviations, and cuing patterns.
Proofreading is the last stage you go through before printing the production copies of a document. In this form of editing, you look at the elements of a document, and it entails making sure that all the changes suggested during the copy edit were done. Barker notes that since this is a tedious process, it is often done with a partner. The following are some of the tasks you perform when proofreading: checking for consistency in the table of contents, checking lists of tables and figures, checking that navigation and routing sequences specify the correct location of the necessary information, cross-referencing the tutorial lessons, checking that screen shots and figure numbers are unique and consecutive, checking that numbered or letter sequences are correctly labeled, and checking that spine copy, bleed tabs, and index pages are consistent.
Plan Your Editing TasksBarker writes that planning for editing should begin at the beginning stages of a project, but that often, editors get brought in later as a last-minute quality control measure. If this happens, you will have to do some retro planning to accomplish the editing tasks. Scheduling depends on the kinds of editing work you will be doing on a project. Depending on how many writers and your editing role, you will have to schedule two things: time for going over documents as an editor, and meetings with authors and developers about your work.
Barker continues his discussion of planning your editing tasks by stating that scheduling editing work allows you to budget in the time you need to complete your editing task and match your activities with others on the documentation team. The time it takes to complete an editing tasks depends on a number of things, including: the quality of the work you receive for editing, and the nature of the material you’re editing. Barker goes on to discuss how to plan for each of the four types of editing.
For managerial, you should plan to attend meetings and edit documents such as the documentation plan, test and review forms, the style guide, and all the documents associated with the project. Communication is the key for this plan and editors need to plan for the following events: establishing styles for print and online documents, a meeting to review the documentation plan, occasional memos to communicate updates to the documentation plan, reminders of deadlines, drafts, reviews, and test activities, periodical updates to the project style guide.
For substantive editing tasks, you should check documents as they are being developed and advise the writer on how to organize and design the content of a document according to the reader’s needs. Barker writes that these editors need to schedule the following events: review the documentation plan and style guide for the project, deadlines for outlines and rough drafts, deadlines for returning outlines and rough drafts, meetings to discuss editing comments and suggestions.
Next Barker discusses what is needed to plan for copyediting. He writes that this type of editing typically only requires on session per draft and is done after all the document is completely written in draft form. Copyediting usually takes longer than substantive editing because you may have to make passes at a document looking for one feature after another. The following are events copyeditors need to schedules: start and end dates for editing sessions on drafts, and meetings with writers and drafters.
The last type of editing to plan for is proofreading. Because of its tedious nature, it is wise to schedule two people for this task. Working as a pair helps to avoid mistakes and letting errors slip. Proofreaders need to schedule the following events: arrange proofreading sessions with another editor, and scan documents for grammar, spelling, headings, graphics, figures, tables, layout, notes, table of contents and index.
Barker notes that you should confuse editing tasks with other tasks, and the following tasks should not be confused with editing: don’t supply missing material, don’t supply missing screen captures, don’t write more than short passages, and don’t edit a manuscript more than once.
Develop the Appropriate Editing FormsBarker writes that because editing requires you to establish relationships with other persons on the documentation team, you will find that creating editing forms, or using existing forms, can help you regularize your procedures and communicate with others more clearly. During document planning, you should have planned what styles the project was going to follow during writing. You should consult your documentation forms when editing to update the project plan, and to identify styles it specifies and reuse as much of the original information as possible. Barker notes that one of the most important forms you can create is the style sheet, which is a way of recording information about your editing convention as you go along. Style sheets are not a substitute for a style guide, which specifies styles for a document ahead of time. Barker emphasizes the importance of a style guide by discussing the purposes it fulfills: regularizing the production of documents, and setting standards that the members of a documentation team can follow. To develop a style guide, you should first look at existing style guides and then consider constructing a style guide for a specific project.
Conduct Editing SessionsThe final guideline Barker discusses is conducting editing sessions. The number one requirement of an editing session is to have no distractions. It is also a good idea to have a checklist handy while you’re editing. To ensure productive editing, Barker suggests two techniques: editing with a partner, and shortening editing sessions.
DiscussionBarker then goes to write about editing graphics and how each of the types of editing relate to this type of editing. He also discusses writing versus editing, stating that when you edit, you should try to see your editing tasks as separate from your writing tasks. This discussion also includes editing for cross-cultural readers by using either a globalized or localized language, and editing for translation, which means writing that is easily rendered into another language.
Campbell concludes this section and the chapter by discussing knowing what is correct, taking a constructive attitude and consulting standard style guides. To know what is correct in your documentation, you should look to guides, users and the documentation plan. Finally, Barker notes that seeing yourself, as a partner instead of an adversary will help your attitude.
