Writing great documentation:
You need an editor
Jacob Kaplan-Moss
November 12, 2009
Part of the
Writing great documentation series.
I’m supposed to be this expert on writing, right? So how come my previous articles have had so many errors?
Simple: my blog doesn’t have an editor.
That’s typical for a blog, but it’s unfortunately also typical of open source documentation: the vast majority of technical documentation doesn’t reach far beyond rough draft status.
All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way. It doesn’t matter how well you’ve mastered the language; nobody, even grammar geeks, gets this stuff right on the first pass.
If you really want to produce great documentation, it needs to be edited.
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.
Comments:
"You’ll be less likely to “know” that you got something *write*, and a little more likely to catch errors." - unless you meant that as a clever pun, it should probably be "right". Sorry to nitpick - should have asked your permission first, of course :-)
"...usual event, so I nobody remarks..."
I sometimes find it easier to print out the hard-to-understand technical documentation parts and use the old fashioned pen and paper method of proofing. I do agree that the person doing the proofing need to be different than the person who wrote the piece in the first place. I could see why. A fresh pair of eyes is always better.
This quote is so true : "There’s almost no way to tell someone they’ve made a writing mistake without sounding like a jerk." Thanks for this documentation series. This is highly interesting, especially since it is coming from one of the author of the best documented project that I know. I think that lots of interesting things could also be told about translation of documentations and the problem of writing in english as as foreign language (as I currently am), where the main advice I would give is KISS. But I guess this is not a problem you have been facing, so, I will have to look for this kind of information elsewhere (or maybe I should write it up myself).
“As a writer, inconsistent editors are maddening.” Something is askew in that sentence. You wanted to start that sentence with either “To” or “For” rather than “As”.
Pretty cool article. I daresay it works for almost every kind of text too. As a journalist I've edited my own text and from other co-workers but never thought so thoroughly of the process. Good job!
I proof grammar by starting at the end and working backwards by sentences. I tend to get caught up in the flow of the text if I read straight through, even if I try stuff like subvocalizing. Once I hit the beginning, I go through forward for flow and coherency. Works great but I still can't edit my own stuff without letting it sit for 3 days or so.
Your text font is looking very weird on Safari for Windows. Looking good on Firefox, though.
As as an employee of a publishing house, it's not so much editors, but 'sub-editors' who are responsible for cleaning up grammer, tense and all other literal issues. 'Sub' is certainly not a good way of describing what these people do, as often the editors are completely reliant upon their cleaning up ...
"...so *I* nobody remarks on the dude in the corner whispering to himself."
Sorry, I just couldn't resist. :)
I agree 100% that it's nearly impossible to proof your own work, but I think you're treating "edit" and "proof reading" to be equivalent. There are many different levels of editing, the most basic is to simply correct grammar and spelling (sometimes called a copy edit). Just as important, though, is editing for accuracy (technical edit, fact checking, etc), and for clarity (organizational edit), both of which can involve substantive changes to the work.
I notice making small mistakes myself, but that's not too tragic. Don't know what the reason is that some mistakes always make it to the final version though most of them get eliminated before (by myself).
Still I wonder how writing in a different language alters that experience, because writing in English really slows me down, I'm so used to writing German, where all nouns start with capital letters and therefore are pretty distinct from other words (so they might be easier to skim).
Any comment on how bad my written English is or how unfamiliar it sounds is welcome. Though I can't write very well in English, I enjoy nice texts (which include "Writing great documentation" modulo mistakes). Well done.
Good stuff. I use Darkroom when I write and then transfer it to Word for the editing phase. Word is just too distracting.
I find many of my errors after I've posted. Doh! At least it's easy to get in there and change the minor nits.
"On top of that, in many larger communities documentation is neglected and still ends up being a solo effort[.]"
I just wrote about the importance of documentation on my blog the other day. It's definitely true that documentation is often neglected in community-wide efforts. A couple of days ago, my roommate was telling me about an interesting modification to a computer game, but it lacked quality documentation. And I'm sure only one person was involved with its creation.
Found this post via Reddit, and I like what I see here. I look forward to reading more about your experiences with writing and editing.
For what it's worth, these are the tips I usually share when people ask me for proofreading advice:
1. Read from the end.
This common tip is simple and effective: read the last sentence first, then the second-to-last, and so on, until you reach the top. Some people take backwards reading to the extreme and read each word individually, starting with the last word. This is an effective way to catch spelling errors, but is not a good way to find errors in punctuation, usage or clarity (did you say what you meant to say?). By reading one sentence at a time, you get a similar isolation effect, but gain the ability to check for more than one type of error at a time. A variation on this tip is to read in the normal order while placing a ruler on the page below the current sentence, causing you to focus on just the words at hand and keep your eyes from reading ahead. This is fine if you have printed your document out, but not terribly useful if you are working electronically.
2. Know your faults.
For whatever reason, we all have words that we stumble on. If there is a word in your text that you have a tendency to misspell, look it up. Even if you think you’ve already run spellcheck, stop where you are and get out the Merriam-Websters or Oxford American (or go to your favorite online dictionary) and double-check the spelling and meaning of the word. If there is a word you aren’t sure of, look it up, even if the spellchecker doesn’t complain.
3. Beware the spellchecker.
Especially if you are using technical or legal terms, don’t assume that spellcheck is correct. (For instance, respondent is an everyday word that the spellchecker likes, while respondant is a legal term that the spellchecker doesn’t know.) Spellchecking software is also notorious for “correcting” unknown proper names and badly misspelled words to terms in its dictionary.
4. Scan the page.
You’ve already read line-by-line, whether backwards or forwards, and you’ve picked out troublesome words and mis-corrections; now it’s time to step back and take in the whole page at once. Let your eyes float over the text and land on anything that sticks out. Counterintuitively, this is a great technique for finding small details. Things like double spaces after periods, inconsistent alignment and other formatting issues stand out when you are less focused on the words and their meanings. You may also notice an excessive use of punctuation — some people are particularly prone to comma abuse — or even several instances of the same word used repeatedly in close proximity.
5. Eliminate distractions.
Stopping and starting while proofing is counterproductive and frustrating. Every time you are interrupted, you must find your place again. Turn off your phone ringer, close your email program (or turn off alerts), and ask your coworkers not to disturb you. If you need to, schedule time in a meeting room and do your proofing there.
Hey, would you mind if I edited your work? ;-)
I am leery of the need for a dictionary when one edits; if an editor has to be looking up a term, what will the poor reader need?
http://mikepope.com/blog/Di...
A style sheet that lists technical terms, that of course is different.
The link at "see below if you must" is broken. It links to href="#self-editing" where it should be href="#s-self-editing".
Great series -- thank you. Crowdsourced editing really seems to jive with the community spirit of opensource. What about tools and implicit editing permissions? After looking at Yard, the Disqus widget on the TG2 docs, Hgbook, ReviewBoard, and pydocweb, I can only imagine the harmonious utility of a versioned and checksummed block-level commenting system (like The Django Books [1,2]) integrated with Sphinx.
[1] http://djangobook.com
[2] http://stackoverflow.com/qu...
Straight-forward suggestions from a veteran docu-mentor. Fantastic!
Leave a comment: