Editing tips

I’m far from an expert editor, but since, in the grand tradition of open source, “we need…” usually translates to “I’m volunteering to…,” I often end up handling the role of editor.

If you do have the opportunity to work with a good editor it’s pretty fantastic and I recommend it highly. One of the best parts of writing a book was learning by being edited.

However, most documentation efforts don’t have the luxury of a real editor. Thus, some advice if you, too, find yourself roped into that role:

• Don’t edit without permission.

  Remember: people writing documentation online are almost always volunteers and often don’t have the benefit of any formal education in writing. They probably are interested in getting better, but ask for permission before you dive in.

  There’s almost no way to tell someone they’ve made a writing mistake without sounding like a jerk, so make sure your criticism has been invited. Nitpicking someone else’s grammar and style because you think of yourself as some sort of expert is just rude.

• Be prepared. Make sure you’ve got your style guide, all your writing reference material, and a good dictionary and thesaurus. You’ll almost always have questions as you go; be prepared to answer ’em.

• Avoid editing your own work (but see below if you must).

  It’s nearly impossible to successfully edit your own work. When you read something you wrote yourself, you know what you meant to write, and so it’s easy to just skip over typos or missing words.

  I do edit the writing I post on this blog, but you’d barely know it judging by the number of embarrassing errors. I’d almost certainly do better if I wasn’t editing my own work.

• Edit on paper.

  As I discussed yesterday, we read online content very differently from print material. We’re a lot more inclined to skim text on a screen, so we miss mistakes that would be obvious in print.

  I edit in red ink, natch.

• Read slowly. The point of editing isn’t to zip through as fast as possible – quite the opposite. You should aim to take as long with each word as possible.

  I actually vocalize the text. I do my editing mostly in public places – coffee shops and libraries – where reading out loud would be weird, but I do subvocalize and silently move my lips as if I was reading each word.

  Thankfully, I live in a town where someone talking to himself at the library is far from an unusual event, so nobody remarks on the dude in the corner whispering to himself.

• Make a couple-three passes. It seems I find about 90% of the errors each pass through. I almost never fail to find something when I make an editing pass, but at a certain point I just got to call it and move on. Two passes is my usual; three is for extra polish.

Above all: be consistent. To a writer, inconsistent editors are maddening. If you’re going to dive into editing, you’ve got to always edit towards the same style.

Self-editing

Now, there’s a strong long tail effect in open source, so most projects end up being the product of a single person. Thus, the documentation is the product of a single person. On top of that, in many larger communities documentation is neglected and still ends up being a solo effort

Thus, in practice “your editor” usually ends up meaning “you.” To that end, some advice on successful self-editing techniques:

• Avoid editing and writing simultaneously. Nothing kills flow worse than continuously second-guessing yourself. So turn off spell-check, turn off grammar checks, and most importantly try to turn off the critical part of your mind until it’s time for editing.

  This is one of the major reasons I end up at a coffee shop or library for editing: I write something, print it out, and the walk over to edit it somewhere else. I’m trying to train myself into thinking of editing as a totally separate role I’m performing that doesn’t even happen in the same place I write.

• Give it some time. If you let some time pass between writing and editing, then what you’ve written will fade a bit from your memory and start to appear a little less familiar. You’ll be less likely to “know” that you got something write, and a little more likely to catch errors.

• Change your margins. This is a really silly trick, but damn does it work. Just change column width or margins in your editor, and when your text reflows it’ll look slightly different. I find that this little difference is enough to jog my brain awake, and I often find things I’ve missed right away after a reflow.

Unfortunately, no number of tricks will really help if you have to self-edit: you’ll still end up with some problems. Ultimately, remember that some documentation always trumps no documentation.

So give it your best shot… but hit “publish” regardless!

What’s next?

Tomorrow, a red pen session: I’ll be editing some documentation provided by a few volunteers, cleaning it up, and explaining my edits.