Field Guide to Technical Editing

Published on Jul 29, 2024 in writing by Chris Wolfgang
8 minute read

You’ve been tasked with some highly specialized material to edit. You’re a pro at writing, but this topic is outside your area of expertise. Now what?

Don’t panic. I’ve got years of experience and a bunch of editing tricks to pass along.

Understand Who Your Writer Is

First, it’s important to understand who the writer is on a professional level. In most cases, the writer of the piece you are editing is a subject matter expert first and a writer second. You can probably trust that the content is correct, or at least that a technical reviewer has given it a stamp of approval. That means you can focus on the quality of your writing.

How much writing experience this expert has can vary greatly. You may be working with a seasoned voice of authority who’s written their own blog for years, or you may be working with a junior developer writing their first tutorial. Knowing this will inform the depth of the edit you should be prepared for. Obviously, a more experienced writer will need a lighter edit than someone who’s just starting to write professionally.

Either way, strive to treat the author with the same respect no matter their writing experience. But we’ll talk more about communicating with writers later.

Do Some Content Research

If you’re going to be working with complex technical content, you’ll have to do some research. Being able to write on the topic yourself isn’t a requirement, of course, but if you’re out of your depth, reading at least the intro paragraph on Wikipedia can get you familiar with a few keywords.

Handling Unfamiliar Jargon

Familiarizing yourself with keywords around the topic is important because, no surprise, deep technical knowledge is full of jargon. Jargon can often come across as poor spelling or grammar if you don’t recognize it.

Fortunately, you can usually satisfy the question, Is this a Tech Thing or is this just awkward writing before introducing errors with a well-intentioned but uninformed edit:

• Search online for the phrase as the author has written it. If it’s commonly used in the industry, you’ll see it pop up regularly in similar content.

  • Double-check the intended audience. Hopefully, this is information you received when taking on the project. If not, this is a perfectly reasonable question to ask.
  • If the audience is, for example, junior developers or nontechnical executives, you may decide to go ahead and ask the author to reword for broader accessibility.
  • If on the other hand the audience is, say, senior developers, leave the jargon in the article as is.

• If you can’t find the jargon with an online search, query your contact (presumably either the writer or whoever assigned you the project) and ask for clarity.

Handling Unfamiliar Concepts

A talented writer will craft sentences you can easily follow, even if you don’t understand the technicality of the content. As an experienced editor, you’ll be able to see points tie into each other and recognize smooth transitions into new sections of information. You know what a good sentence looks like; you don’t necessarily have to understand what every word in the sentence means.

However, you may run across a few paragraphs that impede this smoothness. The concept just isn’t falling into place, or the shape of the writer’s point is still too vague. Has the writer just made some assumptions about their readers’ knowledge and they’ve elected to simply skip over a few details? Is there really material missing that readers need to be able to follow an idea successfully? Or is your writer out of their own depth and the writing is actually weak or inaccurate?

First, try a short online search before querying your author. Remember, you’re working with very technical content written by and for people with a specific knowledge set. You can’t afford to ask for explanations on everything you as the editor are personally unfamiliar with. Not only would that lower your writer’s confidence in your edit, it would also waste time, and you probably have a deadline.

As a general rule, don’t ask questions you can answer for yourself with a quick search. If you’re still unsure, try to ask the project manager (eg, your supervisor or your assigning client) or leave a comment for the writer in the document.

Understand the Type of Edit You’ve Been Asked For

If you’ve been editing for any length of time, you probably appreciate that there are different types of edits. What have you been asked for? A developmental edit? A line edit? A copy edit?

Take care to adhere to the type of edit you’ve been asked for as much as possible. If you’ve been asked for a copy edit, for example, the amount of research you’ll have to do will be considerably less than the other two.

If you do run across something that’s outside the bounds of the edit you’ve been asked for, but you still feel strongly that something needs to be adjusted, leave a comment with a suggested edit. If the entire document needs a heavier edit than what you’ve been asked for, it’s time to get in touch with your manager and let them know you need to make heavier edits.

Avoid Rewriting…Until You Can’t

The line between editing and rewriting can get blurry, but here’s my quick and dirty differentiation:

• Editing: Word-by-word adjustments, retaining the author’s voice while clarifying their meaning.
• Rewriting: Scrapping what the author wrote entirely and creating something new from scratch. Sometimes this means half a sentence, sometimes this means an entire section.

When it comes to complex, technical material, avoid rewriting. The possibility of introducing errors is high. If something is simply not clear, query the writer.

If you feel a rewrite is unavoidable, and you’re itching to make your own words appear on the page, make sure these boxes are checked first:

• You’ve been asked for a heavier edit.
• You have appropriate knowledge of the subject matter.
• The writing skill has been consistently rough.

An inexperienced writer may appreciate that they don’t have to redo a lot of work (that they may not have time for—your technical experts will most likely not be writing as their day job). An experienced writer will not thank you for rewriting their material when a simple query would let them know they need to rework something. Before you rewrite, make sure you’re assessing the situation correctly.

A Word About ESL Edits

When it comes to complex, technical material, it’s not uncommon for authors to be writing in a non-native language. For English-as-a-second-language (ESL) writing, keep the following tips in mind as you edit:

• Be mindful of their voice in English. Would they probably not use a baseball idiom? Do they avoid compound sentences? Don’t introduce them with your edits.
• Punctuation and capitalization have different rules in different languages. English punctuation alone varies between countries (US vs. UK) and style guides (CMS vs. AP). Quietly tidy up copy edits according to the style guide your publication is working with.
• Be respectful and don’t condescend. You are an expert in writing and editing. They are an expert in their subject matter. Recognize that you are helping each other bring a finished product into being, and keep your queries to the writer professional and respectful.

Raise the Alarm for Big Problems

Occasionally, you’ll run into problems an edit just can’t handle. You may suspect that your writer has oversold their own knowledge of the subject matter, or perhaps your research uncovered the fact that your writer has plagiarized.

These problems don’t go away, and if they make it to publication, they can explode in a bad way. Reputations can get called into question, business can be lost, posts can be deleted, and apologies can be necessary.

Inaccurate or Superficial Writing

If you suspect that a writer is simply not capable of writing the material accurately or at sufficient depth, it’s time to call in another expert. If you already have access to a technical reviewer, fantastic—have them look over the piece, highlighting your areas of concern. Otherwise, let the manager know there’s an issue and ask them to suggest a suitable expert, perhaps another developer they trust, for example.

Hopefully the second expert can suggest more specific ways to request that the writer add new information or correct what’s in error. However, be open to the idea that the piece simply may need to be rewritten by someone else, understanding that it will most likely mean a new expense.

AI Use

If you’re an experienced editor, it’s pretty easy to spot AI-generated content. Typically, you’ll see:

• Sentences that say the same thing.
• A paragraph or sentence that doesn’t say anything new.
• Points mirroring the outline without adding any depth.
• Unnecessarily flowery and wordy phrasing.

After cutting any repetition or wordy content, make sure the content you’re editing still has substance. If it doesn’t, you’ll need to ask your writer to expand (in their own words). If the writer can’t expand, they’re likely in over their head and it’s time to bring in the experts.

At Draft.dev, we’re not totally against AI, but there’s definitely a time and place for it. AI struggles with going deep into complex topics. If you’re editing for a highly technical audience, it’s best to probe your author to go deeper and add personal experience, something an AI tool can’t offer.

Plagiarism

If your writer is inexperienced, they may not understand how a quoted citation makes verbatim use of research okay, but it’s plagiarism otherwise. The constant cross-sharing of internet content only blurs the line further.

Plagiarism checkers are a thing, but you can also develop an eye for the red flags yourself:

• A well-written sentence in the midst of an otherwise poorly written article.
• A paragraph with a suddenly different tone/voice.
• Points or sentences that seem to contradict each other (this can also be a sign that an author may not quite have the knowledge base they need or didn’t do careful enough research).

Googling the sentence in question can turn up the original article it was pulled from (Wikipedia articles and other authoritative blog posts are the usual suspects). For a first offense, leave a nonaccusatory, professional query requesting a rewrite in the author’s own words, or a proper quote and citation if a rewrite doesn’t make sense. Obviously, an article that is entirely quoted paragraphs is not acceptable either.

If plagiarism is a pattern with a writer, it’s time to let them go. Their material will be time-consuming to edit, the author’s rewrites will be poorly done, or worst case, you may have to bring in another writer entirely. That’s time and money no one wants to spend. Again, politely and professionally bring this to the manager’s attention.

Conclusion

Highly technical content isn’t the easiest material in the world to edit, but with care and attention, it can be done well. Know your writer, know your audience, know when to ask questions, and be prepared to put in some research, and you’re well on your way to crafting publishable work that’s helpful to its audience.

It does take time to become a skilled editor, of course, and it’s not feasible for every business to employ their own editorial team for their technical publication. If you’d like to publish polished, informative technical writing without taxing your own staff, contact us at Draft.dev to see if we can help.

Build a Blog that Software Developers Will Read

The Technical Content Manager’s Playbook is a collection of resources you can use to manage a high-quality, technical blog:

• A template for creating content briefs
• An Airtable publishing calendar
• A technical blogging style guide

Download Now!