Whenever there are human beings involved, errors are bound to follow. Editing is basically the quality control process for documentation, and so editors are the “QA Engineers for words”. Editors play the role of correcting, condensing, and rearranging content to produce a more correct, consistent, and comprehensive work.
General editing and technical editing are somewhat different. Jonathan Arnett, an Assistant Professor of Technical Communication at Kennesaw State University, says technical editing is “a highly rhetorical, detail-oriented process of ensuring that specialized information appears so that it is appropriate for end users, and technical editors make informed, thoughtful suggestions for improvement toward that purpose.”
Let’s describe the main roles of the technical editor. In this, the first of two blog posts, we’ll look at the stylistic and presentation edits. We’ll talk about copy editing, but you should be aware that larger technical publications teams may separate the duties of technical editing and copy editing into separate roles.
Editing for Style
A stylistic edit seeks to correct problems in the writer’s style that hamper readability for the document’s intended purpose. Potential issues tackled by the editor include ensuring a cohesive narrative, eliminating clutter, and attending to the shape of the document’s beginning, middle, and end. In short, a stylistic edit looks at the language used in the document and attempts to make it read clearly, simply, and perhaps even elegantly.
Stylistic edits need to be made in many particular circumstances. For example, consider a technical manual with inconsistent headers. One writer may have used “Create a New Account” while another used “Deleting your account.” These aren’t technical inaccuracies, but ensuring consistency will improve the document.
Some other cases where you may need to attend to a document’s style:
- Long and convoluted sentences that ought to be broken down.
- Specialized terminology used without first defining it.
- Having a starting paragraph that does not function as an introduction to the whole document.
- Ending paragraph that is too abrupt or feels incomplete.
- Score in readability scoring software is poor.
Technical Publications departments should usually have a style guideline that suggests a manner of writing that is congruent with the brand identity of the organization. For example, Microsoft offers the Microsoft Style Guide and Google offers the Google Developer Documentation Style Guide.
Finally don’t overedit for style. If there is no problem with the writer’s choice of words, there is no need to change the author’s words to similar words that you prefer. For example, if they write “there are good and bad options” but you prefer “there are correct and incorrect options”, there may be no grounds to demand a change.
Editing for Presentation
No editing pass on a technical document is complete without focusing on the presentation: grammar, punctuation, spelling, and diction. A good presentation edit will also find and correct problems that may have been introduced in the desktop publishing or HTML output process. It’s basically another way of talking about the copyedit and proofreading.
Some of the questions to ask when making a document look prettier:
- Is the spelling, grammar, and punctuation solid?
- Are there any typos?
- Do the headline and text square up?
- Are all the photos properly captioned, and do they match the surrounding text?
- Does the document still read well when it is spoken aloud?
Every technical writer should be able to perform a respectable copy edit and proofread, even if it’s not their specialty. They ought to be able to make someone else’s writing look great, catch pesky typos, and eliminate any other problems (even weird stuff like character encoding difficulties with special characters) that might mar the presentation.
Mastering the techniques of style and presentation editing can require a lot of experience and an outstanding command of language, but it is only part of the role of the technical editor. In another blog post we’ll talk about developmental and content editing.