Editing for tech writers

Tech writers don’t just write, we frequently also edit what our peers have written. As Tom Johnson recently tweeted:

Can’t decide if the technical editor role is dead or if technical writers have evolved into this role as their new default.  8:40 AM Apr 23rd

I wouldn’t call it a “default role” for us writers, though the “pervasive idea in companies that ‘anyone can write'” creates more demand for this role (paraphrased from another tweet by Tom three hours later).

I’ll gladly edit the work of another tech writer (and rely on their feedback in return), but I’m less likely to “clean this up by noon”: I’m not grammar boy, and if anyone can write, then anyone can also clean up behind himself… If and how I edit depends on the situation. But what do I mean by editing?

(And what do I mean by that photo? Nothing in particular. Except maybe: How do you illustrate editing? :-))

Editing 101

When it comes to technical editing I have three heroes: Robert Van Buren, Mary Fran Buehler, and Jean Weber. Robert and Mary put together the ultimate tech editing guide back in 1980, called Levels of Edit. An STC edition from 1992 is apparently out of print, but there’s still a summary and a PDF version out there. Their booklet is the most comprehensive and best structured guide to tech editing that I know. They distinguish nine (!) types of edit:

  1. Coordination
  2. Policy
  3. Integrity
  4. Screening
  5. Copy Clarification
  6. Format
  7. Mechanical Style
  8. Language
  9. Substantive

Depending on how thorough your task and how much time you have, you go through all or only some of the levels. In fact, they suggest five different levels of edit for different purposes of a document. Unless you create a production edit for a printing house or publisher, you will probably omit types 1 and 5. The others may be more or less relevant, depending on general policies and what kind of document you’re editing.

I find the nine types of edit so clear and well-structured, because they help me to stay consistent and focused in my editing:

  • When I do an integrity edit to make sure that the table of contents and index are up to date and show the correct page numbers and that all lists are numbered correctly, then I don’t want to worry about misapplied templates, line breaks, text justification and alignment.
  • When I do the mechanical style edit to assure compliance with the corporate style guide, I don’t want to haggle with Oxford commas and dangling participles.

Yes, it does mean that I go through the same document repeatedly, but I find that the additional time spent scrolling or turning pages is made up by the better focus.

Editing the work of others

You can edit your own work, but I don’t recommend it: I find I’m too entangled in my writing, constantly tempted to fix an odd phrase here, a less than perfect table there. If at all feasible, have your work edited by someone else, and edit the work of colleagues.

This is where my third hero Jean Weber comes in (no relation to me): Jean knows all about how to work with editors – or, if you’re an editor, how to work with people who write. She also pointed me towards Levels of Edit.

Jean is in Australia and, according to her website, retired from paid work. But she’s so generous, she shares her knowledge and experience. I found three articles especially helpful:

Your turn

How do you edit? How are your documents edited? Do you edit your own work or someone else’s? Feel free to share issues and insights in the comments.


6 Responses

  1. Agree with your recommendation not to edit your own work. I also find it helpful to put something aside when schedules permit, come back to it later with fresh eyes. I do know grammar well,but when rushed, I find I make embarrassing errors like “no” when I meant “know”.

    I’m very familiar with the Levels of Edit and adopted a similar method when I used to manage a curriculum development team. I think it’s a great starting point for any team where members are expected to wear more than one hat. We don’t have the budget for editors, so we split the role among several team members. Peer TWs edit for standards enforcement and typos. SMEs edit for technical accuracy, and so on.

    As for the odd requests to edit others’ work, I set similar expectations. I’ve learned that when some managers ask for an edit, they expect me to rewrite their drafts. Others are highly insulted if I take such a liberty. So, I always confirm what’s expected and then estimate how long it’ll take me to deliver on that expectation.

    One thing I always try to remember is how customers might read a particular doc. I frequently have to remind Marketing that customers don’t care how cutting-edge or award-winning the technology may be. They care how it’s going to help solve their problems.

    Great post!

    • Thanks, Patty, it’s good to know that some of us keep such a great resource as “Levels of Edit” in use and alive.

      And thanks for pointing out that the conscientious editor has to keep the audience and their purpose in mind just as the writer should!

  2. I started as a tech editor in a research institute, and segued into tech writing at later jobs. Multiple researchers contributed to R&D proposals, reports, and publications. The overriding objective was to produce documents with a single professional voice or tone, regardless of how many different native languages the contributors had.

    I learned that I could only concentrate on one editing aspect or level at a time. I could edit for organization and structure, or for punctuation and grammar, or for clarity and conciseness, but not for more than one of them at a time. I have to make a serarate pass for each aspect, and change my focus each time.

    • Thanks, techquestioner, interesting to hear that some of us were editors first and then moved into writing. (I somehow figured it was more likely to go the opposite direction…)

      I’m part of a multi-language team myself and can confirm that editing (even peer-editing) is essential to get towards a single, professional voice.

  3. […] For more about editing, see my earlier post “Editing for tech writers“. […]

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 )

Facebook photo

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

Connecting to %s

%d bloggers like this: