Writing computer documentation involves converting raw information from engineers and marketing professionals into a useful, well-written document. The final document often is a result of efforts from the entire publications team, including writer, editor, designer, illustrator, and production coordinator. However, the content of the document is most closely developed through the work of writer and editor.
This chapter discusses the following topics:
“Technical Editor’s Role” on page 187
“Editor’s Role in Producing Online Documents” on page 188
“Types of Editing” on page 189
“Edit Schedules” on page 194
“Document Submission” on page 195
“Editing Marks” on page 195
“Edit Style Sheet” on page 195
An editor helps a writer focus on content and effective presentation and provides another set of eyes to check all the details. The partnership of writer and editor produces easy-to-use, high-quality, effective documents.
Any editor is concerned with use of language, flow, tone, grammar, punctuation, capitalization, spelling, sentence structure, consistency, and so forth. However, a technical editor is also concerned with technical content, compatibility of the technical depth with the reader’s background, and effective communication of technical information. Other areas of concern include consistent use of technical terms and symbols, and careful coordination of text and artwork. By marking text and suggesting an alternative, an editor indicates to a writer that the original might be, for example, misleading, awkward, imprecise, confusing, or incomplete.
Editors can help the writers of online documents with the following tasks:
Identify the document’s readers and purpose.
An editor can help a writer use this information to decide which documents to optimize for online, which documents to optimize for print, and how to establish priorities for conversion projects.
Define online document structure and the links that are under the writer’s control.
Writers have control over links that are embedded in the text and links that are in jump lists. However, writers typically do not have control over standard navigational aids such as Back, Forward, and Home, which are predefined in design templates.
Ensure that the document accommodates scanning and nonsequential access by readers.
An editor can help ensure that text complies with online writing style guidelines. See Chapter 4.
Assist with a visual inspection of the online document.
The visual inspection checks for inconsistencies and formatting problems that result from document conversion.
Verify that all links are contextually appropriate.
An editor can review the link wording and surrounding text to ensure that sufficient context minimizes reader disorientation.
Verify that links are appropriately placed within the document to avoid overlinking or underlinking.
Assist with usability testing.
Usability testing can determine whether document navigation follows pathways that readers are likely to follow.
A document could undergo more than one editorial review, each for a different purpose. The type of edit that a document receives usually depends on where the document is in the product cycle. For example, a developmental edit of a document occurs early in the cycle, around the pre-alpha test or alpha period when there might be more time to address issues such as organization and structure. A copy edit is best during the beta review, when the manual is more complete and stable. And finally, proofreading is the last review a document receives.
Developmental editing is hard to define because its functions depend on the documentation set or book under consideration. Think of developmental editing as a document production phase that assesses the document’s overall focus and direction. This edit is the phase when a documentation set or a book is restructured, chapters or sections are reorganized, and major rewriting is done. The issues that the editor raises during a developmental edit can affect the character of subsequent sections or chapters of a document. This effectiveness is increased if the edit is done on a sample chapter or an early draft of a manual. Some global copy editing issues can be raised at this time as well, especially when these issues provide the writer with examples of style or word usage.
Audience definition, purpose of document, and how to use the book are clear.
Information is appropriately presented for the audience.
Concepts flow logically.
Superfluous or redundant material is eliminated.
Headings are useful, descriptive, and specific.
Information is easy to find.
Information is task oriented where appropriate.
Reference and conceptual information are eliminated from task descriptions.
Distinctions between parts and chapters are clear.
Page numbering scheme is appropriate for the type of book.
Reader context is established and reinforced.
Tone is appropriate for the reader and to the focus of the book.
Critical information is covered clearly.
Task-oriented writing is clear. User actions and system actions are distinct.
Assumptions are clearly supported.
Writing and layout are optimized for online presentation.
Terms are used consistently and appropriately.
Terms are defined and used in context correctly.
Terms and abbreviations avoid jargon and follow guidelines for localization.
Documentation set conventions are established and followed.
Document conforms to house publications standards.
Standard templates and formats are used.
Illustrations appear where needed.
Artwork is integrated within the text.
Tables, figures, and illustrations are used effectively and appropriately.
Illustrations follow artwork and localization guidelines.
The editor does minimal rewriting, if any, during a copy edit. Issues regarding structure and organization are addressed throughout the developmental edit. At the copy editing stage, the editor does two kinds of review: mechanical editing and editing for house style. Mechanical editing addresses issues such as punctuation, capitalization, subject-verb agreement, and so forth. Editing for house style involves interpreting and applying your company’s style guidelines. The editor also reads for correct usage of fonts, tags, or other markup, and for structural elements such as tables, illustrations, lists, and procedures. The best time for a copy edit, also called a line edit, is before or during the beta review.
Sentences are clear, direct, and concise.
Repetition is used effectively.
Parallel structure is used effectively.
Headings, lists, and sentences have parallel construction.
Headings follow hierarchy guidelines.
Voice and tone are consistent.
Text is easy to follow.
Information is complete and appropriately placed.
Transitions between parts, chapters, and sections are clear.
Transitions are effective online and in hard copy.
Cross-references are correct, worthwhile, and sufficient.
Sentences are complete.
Subjects and verbs agree, and pronouns and antecedents agree.
Verb tense is consistent.
Modifiers are used appropriately.
Word choice and sentence structure follow guidelines for localization.
Long sentences are divided for readability and localization.
Punctuation follows editorial and documentation set guidelines.
Capitalization follows editorial and documentation set guidelines.
Spelling follows editorial and documentation set guidelines.
Typeface conventions are followed in all document elements.
Product names are used correctly and consistently.
Trademarks are used correctly and include appropriate attributions.
New terms are defined and appear in a glossary if there is one.
Abbreviations and acronyms follow editorial and localization guidelines.
Numbers and symbols follow editorial and localization guidelines.
Cross-references are punctuated correctly and refer to the intended target.
Numbered lists and steps are used appropriately and are numbered correctly.
Figures, tables, and examples are referred to in preceding text.
Table continuations are noted correctly.
Notes, Cautions, and Tips are used correctly.
Footnotes are used correctly.
Running headers, footers, and page numbers are correct.
Document conforms to house style standards.
Standard templates and formats are used.
Page breaks and line breaks are effective.
Page numbering scheme is appropriate for the type of book.
Proofreading is the last step that writers and editors can take to ensure further quality. Proofreading involves one final scan of the document for errors that might have been overlooked in previous reviews. The writer also might have introduced errors when incorporating new technical material or editorial comments. The proofreader’s primary responsibility is to make sure that typographical errors, incorrect font usage, and formatting mistakes have not crept into the document.
Title page shows correct title, company name and address.
Legal notice is current and trademarks, including third-party ones, are listed.
Table of contents includes correct headings and page number references, and is formatted correctly.
Figures, tables, and examples are listed in the front matter.
The preface uses the correct template and contains correct chapter numbers, descriptions, and any required product-specific information.
Appendixes are in the correct order.
Templates and formats are used correctly in appendixes and glossaries.
Glossary is correctly presented.
Bibliography is correctly presented.
Index is formatted correctly and contains no errors.
Sentences are complete.
Subjects and verbs agree, and pronouns and antecedents agree.
Verb tense is consistent.
Modifiers are used appropriately.
Punctuation follows editorial and documentation set guidelines.
Capitalization follows editorial and documentation set guidelines.
Spelling follows editorial and documentation set guidelines.
Typeface conventions are followed in all document elements.
Product names are used correctly and consistently.
Trademarks are used and attributed correctly.
New terms are italicized and defined, and appear in a glossary if there is one.
Abbreviations and acronyms follow editorial and localization guidelines.
Numbers and symbols follow editorial and localization guidelines.
Cross-references are punctuated correctly and refer to the intended target.
Numbered lists and steps are used appropriately and are numbered correctly.
Figures, tables, and examples are numbered correctly.
Table continuations are noted correctly.
Footnotes are used correctly.
Page headers, footers, and numbers are correct.
Change bars do not appear.
Document conforms to house publications standards.
Standard templates and formats are used.
Writers need to allocate time for editing when creating a documentation plan. The nature of the document and the schedule determine how much editing is possible.
Consider these points:
You can involve the editor as early as the research stage.
The editor can help you with research on how similar products are handled and who the audience is.
The editor can help you prepare your documentation plan.
Consult the editor if you want advice on overall organization. Go over your editing needs with the editor and include editing cycles in the schedule.
The alpha review is a good time for a full developmental edit.
Beta review is usually too late to make the kinds of changes that might come out of a developmental edit.
A copy edit at the beta review can clean up grammar, spelling, and conformance to your company’s style standards.
Proofreading before the final release provides one last check for formatting issues and typographical errors.
If you are writing a white paper or other nonstandard document, plan to allow time for developmental edits and copy edits.
Before submitting a document for editing, complete these tasks:
Run your document through a spelling checker.
Check cross-references.
Include illustrations or indicate placement of illustrations.
Include a Request for Editing form with the document you submit. This form supplies information such as your name and phone extension, the stage of the document (alpha, beta, final release), and the name of the set to which the document belongs. See “Request for Editing Form” on page 305 in Appendix B for a sample form.
Your editor will be glad to explain any editing marks that were used in the edit. You can find an online guide to editing marks at the University of Colorado at Boulder Web site. For an explanation of standard proofreaders’ marks, see The Chicago Manual of Style, Fourteenth Edition, or Merriam-Webster Collegiate Dictionary, which is available online at http://www.m-w.com.
Maintaining a style sheet can help you keep track of special spellings, terminology, punctuation, capitalization, and other document-specific words or formats.
A style sheet is where you and the editor can log the decisions made about product names, numbers, abbreviations and acronyms, hyphenation, and capitalization. If the document that you are writing or editing is part of a set, using a style sheet helps maintain consistency among the various books.
When you create a style sheet, remember to pass it on to others who might benefit from it. These people might include writers of related documents, editors, illustrators, and production specialists.
A sample style sheet form follows.
