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

Technical Editing in the 20Teens

Embed Size (px)

DESCRIPTION

Mini-workshop given to #STC-SD in November 2010 on technical editing

Citation preview

Page 1: Technical Editing in the 20Teens

Technical Editing in the Twenty Teens

Adding quality to our products through editing

Linda Oestreich20 November 2010STC-SD Workshop

Page 2: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 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

Page 3: Technical Editing in the 20Teens

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

Page 4: Technical Editing in the 20Teens

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 development firm Lots of experience in different roles—writer, editor,

and manager

Page 5: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 5

Who are you?

Writers? Editors? Managers? Liberal arts? Science/tech/IT? Companies? Why here?

Page 6: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 6

Warm-up exercise!

Hurricane exercise– Copy edit…spelling, punctuation, etc.

Page 7: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 7

Topic Overview

What’s in your editorial toolbox? Do the mechanics change? What makes your product usable/readable? Do you edit online or on paper? What’s it like in today’s work place for

editors/editing? References for us all

Page 8: Technical Editing in the 20Teens

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 (see ref)– 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

Page 9: Technical Editing in the 20Teens

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

Page 10: Technical Editing in the 20Teens

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

Page 11: Technical Editing in the 20Teens

Why 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 11

Page 12: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 12

1. Sample 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

Page 13: Technical Editing in the 20Teens

2. Sample editing types/levels

1. Legal review– Ensure compliance with legal requirements

2. Format review– Ensure compliance with publishing requirements

3. Minimum copy edit– Spelling, punctuation, accuracy, consistency, adherence

to corporate and departmental style

4. Standard language edit– Appropriate for primary audience, organized appropriately,

clear

Oestreich/20 Nov 201013

Page 14: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 14

3. Classic “Levels of Edit” from Jet Propulsion Laboratory (1976)

Type Level of Edit

Level 1 Level 2 Level 3 Level 4 Level 5

Coordination X X X X X

Policy X X X X X

Integrity X X X X

Screening X X X X

Copy Clarif. X X X

Format X X X

Mechanical X X

Language X X

Substantive X

Page 15: Technical Editing in the 20Teens

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.

Tone, style, and content

Page 16: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 16

Comments in Acrobat

Page 17: Technical Editing in the 20Teens

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

Page 18: Technical Editing in the 20Teens

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

Page 19: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 19

Editor or predator?

Exercise!

Page 20: Technical Editing in the 20Teens

What traits make a good editor?

Personality? Skills? Talent?

Class discussion!

Oestreich/20 Nov 2010 20

Page 21: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 21

Editor or writer: do you agree?

Typical editor traits: Generalist Wide focus (“forest”) Short project cycles Multiple projects General familiarity

with many products or services

Likes stability

Typical writer traits: Specialist Narrow focus (“trees”) Long project cycles One project at a time Intimate familiarity with

a few products or services

Likes “cutting edge”

Page 22: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 22

What about the mechanics?

Any changes in last 50 years?– Spacing?– Language?– Date driven

What gray areas do you feel strongly about?– Capitalization? Serial comma?– Good style guides eliminate gray areas!

Page 23: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 23

Reviewing punctuation, grammar, and usage

Colons, semicolons, and commas

Hyphens and dashes Parentheses and

brackets Parallelism

Lists Subject/verb agreement Dangling modifiers Noun strings Passive voice Style sheets!

Page 24: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 24

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.

Page 25: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 25

Untangle these danglers

1. Now you can recondition your furs while hanging in the closet.

2. By wearing carefully selected glasses, the scars were completely hidden by the side pieces.

3. Being only 3 feet tall, you can easily see why the bus ran over the child.

4. The couple sat watching the sun set in sandy bathing suits.

Page 26: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 26

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.

Page 27: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 27

Humorous mistakes

I once shot an elephant in my pajamas…how he got there, I’ll never know!

Page 28: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 28

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.

Page 29: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 29

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.

Page 30: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 30

Five C’s always good baseline

Clear Concise Consistent Correct Concrete

Page 31: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 31

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.

Page 32: Technical Editing in the 20Teens

Practice reviews

Trade papers with someone and let them edit your edits!

Oestreich/20 Nov 2010 32

Page 33: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 33

Do you edit on paper or online?

On Paper?– Benefits– Challenges– Practicality

Online?– Plain text– Microsoft Word– Adobe Acrobat/PDF– Other programs?

Page 34: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 34

Editing online or on paper?

Two or more passes Online style sheets Spelling and grammar checkers Accepting and rejecting comments One editor’s opinion

Page 35: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 35

Writer checklist: Completed when submitting information for an edit

Page 36: Technical Editing in the 20Teens

Managing editing

Changes Quality and metrics Getting it done Usability Localization needs

Oestreich/20 Nov 2010 36

Page 37: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 37

What’s it like in today’s work place for editors/editing?

How to get it done– Who does it?– How to hire when you can

Expectation exists that professionally produced documentation will be edited

International outsourcing increases the need Clear communication is a valued skill or is it?

Page 38: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 38

Editing choices

No editing Self-editing Peer editing Writer acting as editor Manager as editor

Page 39: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 39

No editing?

Despite an increase in unedited communication… – E-mail, text messaging– Blogs– Podcasts

. . . editing is still a widely recognized need

Page 40: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 40

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

Page 41: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 41

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?

Page 42: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 42

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

Page 43: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 43

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

Page 44: Technical Editing in the 20Teens

Editorial checklist?

Oestreich/20 Nov 2010 44

Page 45: Technical Editing in the 20Teens

Editing “cheat sheet”

Oestreich/20 Nov 2010 45

Page 46: Technical Editing in the 20Teens

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

Page 47: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 47

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?)

Page 48: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 48

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?

Page 49: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 49

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."

Page 50: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 50

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.

Page 51: Technical Editing in the 20Teens

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 51

Page 52: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 52

Thoughts on value

Value of editing: can anybody do editing? Language correctness: how exacting? When do you

yield? If customers won’t notice, should you? Process and organizational flexibility: Are you willing

to compromise? Interpersonal dynamics: Who has the authority?

What if you’re wrong? Do you justify every edit? Record keeping: Do you keep all edited drafts? A

logbook? Lists of agreements?

Page 53: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 53

Editor’s relationship to writing

“An editor’s relationship to writing should be the same as a bartender’s relationship to drinking . . . s/he should be fond of an occasional drink, but it shouldn’t be a regular habit.”

(Gordon van Gelder, Night Shade Books discussion area: http://www.nightshadebooks.com/discus/messages/378/3395.html?1099195815)

Page 54: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 54

My mentor’s advice

“A good way to improve editorial skills is to teach someone else in a one-to-one, tutorial relationship. With a bright, assertive apprentice who questions and challenges every aspect of the work, you’ll find yourself reviewing rules you’ve grown careless about, looking up items you’ve taken for granted, sharpening style—all because you had to take a fresh look at things that had become so familiar you didn’t even see them any more.”

“Lessons from 50 years Editorial Experience,” Lola Zook, Substance & Style, 1996, EEI Press

Page 55: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 55

References for us all

“Training the Editor: Skills Are Not Enough,” Lola M. Zook, STC Proceedings, 1967

Guide for Beginning Technical Editors, Wallace Clements and Robert G. Waite, STC-112-83

“The Editor as Ally,” Laurel K. Grove, Technical Communication, volume 37, number 3, 1985, pp. 235-238

The Motion Picture Editors Guild Newsletter, Vol. 19, No. 4, July/August 1998 http://www.website-articles.net/Article/Technical-Writing---How-to-Generate-

Localization-Ready-Technical-Copy-With-Pre-Production-Guidelines/30714 http://www.useit.com/alertbox/20030825.html Jakob Nielsen's

Alertbox:Usability 101: Introduction to Usability http://en.wikipedia.org/wiki/Readability Levels of Edit, http://www.technical-expressions.com/learn2edit/levels-of-

edit/levels_of_edit.pdf

Page 56: Technical Editing in the 20Teens

Oestreich/20 Nov 2010 56

References (continued)

Hart, Geoff. Effective onscreen editing. http://www.geoffhart.com/books/eoe/onscreen-book.htm

Baker, Donna L. Adobe Acrobat 9: How-Tos, 125 Essential Techniques. Adobe Press, 2009.

Kelly, Will. “How to Use Adobe Acrobat for Online Document Reviews.” http://webworkerdaily.com/2009/09/03/how-to-use-adobe-acrobat-for-online-document-reviews/

Troffer, Alysson M. “Editing Online Documents: Strategies and Tips.” Proceedings from the 49th Annual STC Conference.

Crognale, Heather. “Long-distance editing: Tips for editors on managing the writer/editor relationship.” Intercom, July/August 2008, pp. 17-19. http://www.stc.org/intercom/PDFs/2008/20080708_17-19.pdf

Oestreich, Linda. “Editing with heart” workshop presentation to 49th STC Annual Conference, May 2002

Corbin, Michelle. “Effective Editing Comments” Webinar presented to TE SIG in 2009. Adobe Acrobat User Community: http://www.acrobatusers.com/ Zook’s article Tice, Anne L., Data General, “Levels of Edit: An Introduction and A Strategy,”

(presentation) 18 May 2000 Intercom, Dec 2001, Angie McNeill, Oklahoma chapter “technical editing 101”