What to Look for When Editing Technical Material

When I’m given existing technical material to edit, I have some basic items that I look for to make the content more engaging, robust, and easy to read. These are the types of edits I do when I’m asked to “Make this sound like English” and I’m given carte blanche to change things to my heart’s content.

Content

  • Make sure you understand who the audience is, under what circumstances they will be reading it, and what they need out of the document. I call these my two most important questions.  By understanding your audience, context, and intended outcome, you can better shape the tone and emphasis of the content. And while you’re at it, you want to make certain that the content is meeting the audience, situation, and outcomes the original authors intended.
  • Ensure that the main point/summary is up front. As I’ve noted elsewhere, scientists and engineers often assume that the purpose or benefit of their particular project is so obvious that it does not need to be stated up front in plain language. I disagree. I go into a document thinking like a non-techie manager or a bureaucrat, which is close to my actual role. I need and expect my “so what?” text to be up front. This should be something like, “We are building X Widget to make Y process better/cheaper/faster to achieve end result Z.”
  • Ensure that the content/order is complete and makes sense. Sometimes you might encounter a document where explanations are left out or the order of operations seems contradictory or confusing. If that’s the case, call them on it and attempt to clarify: “Did you mean to say…X?”

Mechanics

A content edit is about making certain that the content is correct, makes sense, and fits together. This differs from copyediting, where you’re just looking for grammar, spelling, punctuation, and formatting. I have yet to restrain myself from doing copyediting while doing a content edit, and generally, if I’m given free rein to fix the document, I’ll be expected to do it anyway. The challenge with doing too much copyediting during a content review is that you might end up wasting time fixing minor nits on a sentence or paragraph that ends up getting pulled anyway.

Sometimes you need to educate your customers on the difference between content and copy editing and the process they want to follow. You might, for example, suggest a content edit first to ensure that the document has all the information it should in the proper order before you go in and do copyediting on the next draft. This is not to say you shouldn’t copyedit, but be judicious about it if the content is due to go back to the SMEs for review.

  • Enforce active voice where feasible. Some organizations are stylistically allergic to using any sort of individual or even corporate voice. “The magnet was moved” is more common than “I/we/the team moved the magnet,” and it makes for dull reading. Passive voice adds words unnecessarily and dilutes the message. If your organization is similarly averse to having actual people in their prose, see if there are ways to make the widget active: “The Space Launch System enables larger payloads to be launched into space and ensure increased science capabilities beyond Earth orbit.”
  • Keep subjects and their actions close. For some reason, it can be tempting to add a lot of explanatory text between the subject of a sentence and the action it is performing. Let me see if I can make up an example. “The five-segment reusable solid rocket booster (RSRB), using polybutadiene acrylonitrile (PBAN) propellant aboard and providing immediate, increased thrust during liftoff, burns for a little over two minutes before being jettisoned.” The subject in this case is the solid rocket booster or RSRB. And while there are a couple of gerunds in there (using and providing), the actual verb the RSRB performs is burns. There are something like 13 words separating the actor for its action. Again, the impact is diluted. There are a couple of ways you can fix this, including breaking up the sentence into a couple sentences or you could move the words around so that the action is closer to its subject: “The five-segment reusable solid rocket booster (RSRB) burns its polybutadiene acrylonitrile (PBAN) propellant for a little over two minutes, providing immediate, increased thrust during liftoff before being jettisoned.” There are doubtless many other ways you can tweak this sentence and make it shorter. The goal here is simply to make the action more connected to what is performing the action.
  • Maintain parallel structure. This can follow a couple of different tracks. For instance, making certain that the first word in each bullet point is a verb. Another thing to do would be to ensure that items of equal importance have equal length as well as a similar structure. For example, if you’re describing a series of objects, you would describe them in a similar order, say, by physical description, then function then size, then capability, then by safety features. Sometimes adding subheadings can keep this order better organized and ensure that each attribute is covered.
  • Unify writing styles. It’s not uncommon for for multiple to write a document and for  word choices, tenses, and even tone of “voice” to shift dramatically as the content moves from author to author. The trick, as always, is to make certain that the entire document reads as if one person wrote it. That topic might require a separate entry all to itself, but for now the simplest way to ensure a consistent style is just to read the entire thing and ensure that it reads in a consistent style that you can live with (it might not necessarily be your style).

Other items can and do come up when you’re editing, such as ensuring that acronyms are spelled out the first time they’re used, but these are the sorts of things that I’ve conditioned myself to spot and fix given the opportunity to do full-scale technical editing. if you have other “favorites,” feel free to share in the comments below!

About Bart Leahy

Freelance Technical Writer, Science Cheerleader Event & Membership Directior, and an all-around nice guy. Here to help.
Quote | This entry was posted in clients, documents, editing, science, technical writing, workplace. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s