By Michelle Corbin | STC Fellow
I started my career as a technical writer at IBM, and I had to submit my drafts to a technical editor. My technical editors (thankfully) never used the dreaded red pen that harkened back to my high school English teacher marking up my essays, but they did become some of my favorite teachers. Sure, they taught me the style guides we used, but they also taught me how to be a better technical writer. They did this through their editing comments that they inserted next to the editing markup.
Editing Comments
Technical editors can phrase their editing comments in a variety of ways, all of which help teach technical writers how to improve their writing:
- Imperative comments are direct statements that are based on facts, guidelines, standards, or requirements.
- Suggestions are indirect statements that present an alternative way to address a potential problem that usually reflect a guideline, standard, or requirement. (Opinions are suggestions that are not grounded in such things.)
- Queries are comments that point out the ambiguity of the information and ultimately clarification is required.
Technical editors can use each type of editing comment to go beyond the markup and teach the writers the “what, why, and how” of making the change.
What, Why, How
As technical editors, we must work hard to build a good relationship with our technical writers. If technical writers respect their technical editors, and they trust that you are both working together to improve the information for the user — that you are “partners in quality” — then they are more likely to accept your changes and revise the text. And, they will be more open to learning more about their writing craft along the way. This is the why of editing comments.
How technical editors phrase editing comments is critical. Obviously (hopefully, this is obvious!), technical editors must use tact and diplomacy while providing positive, constructive feedback. What technical editors say is equally important.
For example, you might have seen this comment from a harried English teacher, “Awkward. Rewrite.” Instead, a more detailed, teachable editing comment might be: “This is awkward because of a long noun string in a long, complex sentence. Can you break this into two sentences?” The former puts the author on the defensive, while the latter actively tries to improve future efforts.
In reviewing some of my editing comments from early in my technical editing career, I found this comment that I provided in an edit: “Don’t use so much italics.” Now, I see the missed opportunity to teach the writer why our style guide discourages the use of italics. Today, I’d write my editing comment like this: “Italicized text is difficult to read online. Use italics to identify new terms only. Use monospace for info the user must type. Review the highlighting entry in our style guide.”
Technical editing is a very critical task, one that feels like we are trying to fix all the errors and problems at one time. We need to remember to take a step back from the criticism and focus on the strengths in the writing, too! Be sure to highlight what your technical writers did well or what you easily understood from their writing.
Summarize and Prioritize
One last teaching tool for technical editors is to write a short editing report (a paragraph or two) that summarizes and prioritizes your editing comments. When technical writers sit down to try to revise their information, it is easy to be overwhelmed by all the markup and all the editing comments in the margins. So, a short editing report goes a long way to adding context and preparing them for the best way to improve the information.
Explaining what, why, and how in our editing comments not only improves the current document, but also improves the writer’s contributions to future projects. This teaching streamlines the process, saves time, and has a direct impact on the department’s bottom line.
MICHELLE CORBIN covers matters (topics) about editing that are of consequence to communicators of all kinds in Editing Matters. She helps communicators understand more about editing and what they can do to improve the quality of their content. To suggest a topic, or ask a question, contact Michelle at michelle.l.corbin@gmail.com.
