Technical Editing in the Twenty Teens

1. Technical Editing in the Twenty Teens Adding quality to our products through editing Linda Oestreich 20 November 2010 STC-SD Workshop

2. Editorial wisdom “The work of a good editor, like the work of a good teacher, does not reveal itself directly; it is reflected in the accomplishments of others.” • The Motion Picture Editors Guild Newsletter, Vol. 19, No. 4, July/August 1998 Oestreich/20 Nov 2010

3. Who am I? • STC Fellow & board member at chapter and Society level • Strategic analyst • Technical communicator: manager, editor, writer • Teacher, trainer, instructional designer Oestreich/20 Nov 2010

4. Why me? • Writer/editor for science/engineering • Communications manager and editor for geophysical software development company • Policy and procedures writer/editor for corporate offices of young software firm • Executive of small communications consulting firm • Editor for large software developmentfirm • Lots of experience in different roles—writer, editor, and manager Oestreich/20 Nov 2010

5. Who are you? • Writers? • Editors? • Managers? • Liberal arts? Science/tech/IT? • Companies? • Why here? Oestreich/20 Nov 2010

6. Warm-up exercise! • Hurricane exercise • Copy edit…spelling, punctuation, etc. Oestreich/20 Nov 2010

7. Workshop overview • What’s in your editorial toolbox? • Types and levels of edit • Commenting with care • Mechanics of editing • Editing on paper or online • Managing the editing • Readable, usable, localizable? • Looking ahead • References Oestreich/20 Nov 2010

8. What’s in your editorial toolbox? • Basic necessities & physical items • Style guides (general & industry-specific) • Dictionary/grammar checker • Check lists & style sheets • Editing system (proofreaders’ marks, etc.) • Software • Soft skills & knowledge base • Use of English language • Data presentation (information architecture) • Content strategy • Editing types/levels • Editorial commenting • People skills Oestreich/20 Nov 2010

9. Style guides • Chicago Manual of Style • Elements of Style • GPO Style Manual • American Psychological Assoc. • Modern Language Assoc. • Associated Press • Council of Biology Editors’ Style Guide • Microsoft Manual of Style • US Navy Style Guide Oestreich/20 Nov 2010

10. Proofreaders’ marks • Insert letter • Insert period • Transpose • Delete • Lowercase a letter • Uppercase a letter • Italicize a word (unitalicize?) • Boldface a word (unbold?) • Stet Oestreich/20 Nov 2010

11. Editing types & levels • Establish a common language • Help manage schedules • Facilitate budgeting and labor tracking • Provide guidelines for peer edits • Levels are based on combination of types to create higher and higher “levels” of attention and quality Oestreich/20 Nov 2010

12. One set of editing types • Copy edit • Textual markup of language • Grammar, punctuation, style • Focus: Sentence-level, word-level • Substantive edit • Inserting queries or comments about the content • Organization, usability, logic • Focus: Topic-level, paragraph-level Oestreich/20 Nov 2010

13. A second set of editing types • Legal review • Ensure compliance with legal requirements • Format review • Ensure compliance with publishing requirements • Minimum copy edit • Spelling, punctuation, accuracy, consistency, adherence to corporate and departmental style • Standard language edit • Appropriate for primary audience, organized appropriately, clear Oestreich/20 Nov 2010

14. The classic set of editing types “Levels of Edit” from Jet Propulsion Laboratory (1976) Oestreich/20 Nov 2010

15. Editorial commenting • Comments are statements that an editor makes to the author to improve the information. • Types of comments: • Imperative - an editing comment based on facts, guidelines, standards, or requirements and that must be addressed in some way • Suggestion - An editing comment that presents an alternative way to address a problem and that the writer can choose to implement • Opinion - An editing comment that represents the opinion of the editor and does not reflect a specific guideline, standard, or requirement. • Query - An editing comment that aims at pointing out ambiguity of information, or that expresses a need for the editor’s enlightenment. • Be mindful of tone, style, and content Oestreich/20 Nov 2010

16. Comments in Acrobat Oestreich/20 Nov 2010

17. Objective editing • Correct all misspelled words and punctuation errors • Correct errors in grammar • Coordinate text, figures, tables, indexes, breadcrumbs, etc. • Check for consistency in such things as spelling, abbreviations, names of things, and numeral usage • Check facts and references • Mathematical/scientific notation • Zero or O • Tables & figures content Oestreich/20 Nov 2010

18. Editors and writers as allies • Keep reader/user in mind • Agree ahead of time on rules and roles • Cosmetics or neurosurgery? (levels of edit) • Ask questions: understand the purpose • Listen and explain • Review the logic • Reference everything you change Oestreich/20 Nov 2010

19. Editor or predator? • Exercise! Oestreich/20 Nov 2010

20. What traits make a good editor? • Personality? • Skills? • Talent? Class discussion! Oestreich/20 Nov 2010

21. What about the mechanics? • Any changes in last 50 years? • Spacing? • Language? • Date-driven products? • What gray areas do you feel strongly about? • Capitalization? Serial comma? • Good style guides eliminate gray areas! Oestreich/20 Nov 2010

22. Colons, semicolons, and commas Hyphens and dashes Parentheses and brackets Parallelism Lists Subject/verb agreement Dangling modifiers Noun strings Passive voice Style sheets! Reviewing punctuation, grammar, and usage Oestreich/20 Nov 2010

23. Rewrite by using a list: You should sign block 23 of form 2139 if you make over $50,000, are a resident of the city, and are under age 65, or are self-employed in the city. Oestreich/20 Nov 2010

24. Untangle these danglers • Now you can recondition your furs while hanging in the closet. • By wearing carefully selected glasses, the scars were completely hidden by the side pieces. • Being only 3 feet tall, you can easily see why the bus ran over the child. • The couple sat watching the sun set in sandy bathing suits. Oestreich/20 Nov 2010

25. Misplaced modifiers • The ticket agent told us eventually the train would arrive. • Sharon decided the next day to start studying. • A train stopped at our town only on weekends. Oestreich/20 Nov 2010

26. Humorous mistakes • I once shot an elephant in my pajamas…how he got there, I’ll never know! Oestreich/20 Nov 2010

27. Active and passive • Passive Mother Goose • Hickory, dickory, doc, the clock was run up by the mouse. • Hey diddle, diddle, the cat and the fiddle, the moon was jumped over by the cow. • The tuffet was sat on by Little Miss Muffet while her curds and whey were eaten. • When the subject of the verb is acted upon, the sentence is in passive voice. • When the subject of the verb acts, the sentence is in active voice. Oestreich/20 Nov 2010

28. Ambiguity • After stirring for 10 seconds, add three drops of solution to the iodine mixture. • The manager told Mr. Jones and then he told me. • The records include all test reports for engines received from the new test facility. • John said during lunch he would take a walk. Oestreich/20 Nov 2010

29. Five C’s always good baseline • Clear • Concise • Consistent • Correct • Concrete Oestreich/20 Nov 2010

30. Practice • There are at the present time in the vicinity of Dayton three similar systems installed and operating, and each system generates a monthly quantity of reports equal in volume to approximately one-half its total 2005 output (about 300 pages), then these reports are stored on location or distributed for reference purposes. Oestreich/20 Nov 2010

31. Practice reviews • Trade papers with someone and let them edit your edits! Oestreich/20 Nov 2010

32. Do you edit on paper or online? • On Paper? • Benefits • Challenges • Practicality • Online? • Plain text • Microsoft Word • Adobe Acrobat/PDF • Other programs? Oestreich/20 Nov 2010

33. Editing online or on paper? • Two or more passes • Online style sheets • Spelling and grammar checkers • Accepting and rejecting comments • One editor’s opinion Oestreich/20 Nov 2010

34. Writer checklist: Completed when submitting information for an edit Oestreich/20 Nov 2010

35. Managing editing • Current situation • Quality and metrics • Getting it done • Usability • Localization needs Oestreich/20 Nov 2010

36. Today’s work place concerns? • Expectation exists that professionally produced documentation will be edited • International outsourcing increases the need • Clear communication is a valued skill or is it? • How to get editing done • Who does it? • Constraints and rewards of several scenarios Oestreich/20 Nov 2010

37. Editing choices • No editing • Self-editing • Peer editing • Writer acting as editor • Manager as editor Oestreich/20 Nov 2010

38. No editing? • Despite an increase in unedited communication… • E-mail, text messaging • Blogs • Podcasts • . . . editing is still a widely recognized need Oestreich/20 Nov 2010

39. Self-editing? • Good writers self-edit • New writers should self-edit • Editing checklist • But technical communication needs more • A fresh set of eyes • An objective review • A usability review • Quality assurance Oestreich/20 Nov 2010

40. Peer editing? • Can use in combination with a formal technical editor • Most common alternative • Difficult to allocate the time needed • Difficult to maintain consistency • Difficult to settle disputes • Who will own the style guide? Oestreich/20 Nov 2010

41. Writer acting as editor • Ad hoc appointment • If editor moves to another group or quits • Stopgap measure imposed by management • Political consequences within the group • Sink or swim for an inexperienced editor • Opportunity for professional development Oestreich/20 Nov 2010

42. Manager as editor • Can work in some situations • If manager is experienced editor • If group is new and uncongealed • If group is small • Blurs distinction between two very different roles • Difficult to allocate time Oestreich/20 Nov 2010

43. Editorial checklist? Oestreich/20 Nov 2010

44. Editor’s “cheat sheet” Oestreich/20 Nov 2010

45. What do you measure? • Defining quality and value • Adhering to guidelines • Meeting defined criteria • Exhibiting quality characteristics • Satisfying customers • Improving usability testing • Increasing productivity Oestreich/20 Nov 2010

46. Quantifying your measurements • Any metric is valid: if consistent and applied appropriately! • Begin with baselines, then use same metrics over time • Track # of hours spent on various edits • Develop metric for average # of pages per hour • Track editing of new vs. changed pages • Track percentage of deliverable edited • Caveats: Some industry standards exist, but those based on your context and your productivity are best (for example, what is a page or a topic? what is the markup style?) Oestreich/20 Nov 2010

47. What makes your product usable/readable? • Can it be readable and not usable? • What about the reverse? • What makes something well-written? • What about localization/translation issues? Oestreich/20 Nov 2010

48. Readable or usable or both? • Readability is commonly defined as reading ease.The Literacy Dictionary defines it as "the ease of comprehension because of the style of writing." • In human-computer interaction and computer science, usability studies the elegance and clarity with which the interaction with a computer program or a web site (web usability) is designed • ISO defines usability as "The extent to which a product can be used by specified users to achieve specified goals with effectiveness, efficiency, and satisfaction in a specified context of use." Oestreich/20 Nov 2010

49. Localization considerations • Exclude all culturally-specific idioms, conventions and expressions since they are hard or impossible translate to another language • Include the open written forms of all abbreviations and acronyms the first time they are used. And the rule here is: the less, the better • Include a Glossary which should define all the technical terms and concepts used in the source document. • Include a Unit and Measurement Conversion Chart • Include a list of terms and concepts that should NOT be translated and used as-is since they may sound awkward in the local language when translated. Oestreich/20 Nov 2010

50. International edits • Consistent wording—saves money, adds clarity • Passive voice—saves money, adds clarity • Phrasal verbs—not “speed up” but accelerate; not “look over” but review • Metric equivalents—use them! • Articles—clearer construction (XYZ allows air to intake manifold) • White space—use it—other languages will use it! Oestreich/20 Nov 2010