This is about writing, not .NET so if that is all you care about, you can stop reading.
I just received a compliment from my editor that I’m easy to work with on review. I realize this is a process many people don’t understand. I’ve worked with some great editors (including Patrick Meader at Visual Studio Magazine), so I thought I’d take a minute to explain the process. If you hope to write this is likely to help you, and if you already write you might have to apologize to an editor. Regardless you might learn something.
Now, I’m assuming you have a good editor. Honest to goodness, I had an editor once insert into my piece “now that we’ve got the bun let’s look at the meat” and yes it was much closer to the “where’s the meat” ads on TV than we are now. As you can guess, I blew my top and didn’t work with that editor again. I wish him well in his creative endeavors; my article just wasn’t his creative endeavor.
Few editors are like that. Almost all editors are good. If you want to write, I think Stephen King’s book “On Writing” is worth a read. King says “the editor is always right.” This is really hard for writers to hear and believe, so let’s back up and look at the process I’ve experienced, and then explain what I think King’s comment means.
For a magazine, I write an article and submit it. The editor sits on it for up to six weeks because his schedule is at least as demanding as mine. He edits it, sometimes in crises mode, and sends it back to me shortly before the issue goes to layout. Now, every editor in the world is going to say “I try not to do that” but reality is reality. Once I get the editors changes for my review, I need to turn them around in a very short period of time, generally less than 72 hours, occasionally less than 24.
What I get back is a Word document with a lot of red ink – I think my editor’s review is set to blue which is slightly less depressing. Remember, I write about 15 articles a year that are edited by the same person and about 1/4 of what I see is mark up. That’s a lot of red ink. You’re job is to write a great technical article. The editor’s job is to supply proper grammar and consistent voice to a magazine. All that red ink is the editor doing their job to make you look good.
Here’s what really important: The editor is always correct that he made a change, but NOT always correct in the change he made. It is a huge mistake to just say “yeah, go with it.” The editor’s main job is to find problems – their job is NOT to solve problems in your article. The easiest way for the editor to communicate the problem is to offer an alternative. Nine times out ten, well at least eight times out of ten, their fix is good. I’m terrible about “backing into sentences” although I’ve finally gotten better about passive voice. I’m very careless with tense and everyone struggles with ambiguity in “it,” “this,” etc. This the majority of fixes – along with formatting details specific to the magazine that you’re unlikely to ever care a lot about (Listing references are in parentheses, for example).
It’s your job to read the article review and look at every change the editor made. That means you turn on Final With Markup and turn it off when you need to ensure the final flow. You should have a mechanism for asking questions like “why did you change this” for the purpose of learning, but rarely for the purpose of this article. Discussions for resolution of this particular article are almost never worthwhile. If the editor thinks your way is wrong, and you think the editor’s way is wrong, there is always a third way, a fourth way, or a fifth way. It’s your idea, rephrase it to make it more clear.
If you look at a particular spot of red ink that you hate, you’re first question should be “what was I trying to say?” This generally points directly to a better way of saying it. It should never be about whether what you wrote was correct. It’s a collaboration, not a contest. What you wrote may be correct, but it tripped up the editor and there’s a better way to say it. Occasionally, ask so you learn for the next article – for this one, just fix it. You have Track Changes on and can change what you need to. Do not accept or reject anything, just change it again. If you really believe you have to say it the initial way, find a way to prefix or postfix it for clarity, often with another sentence.
At least a few of the edits in nearly every article of mine is because I go out on a correct, but non-critical side case or tangent (anyone who has heard me speak just giggled as it is one of my lifelong sins). This “or …” is confusing because there’s no context. If it’s important, such as a landmine in the process, I expand it to a full sentence or two explanation. If it’s not important I drop it.
When you get a review, you check it make potentially a number of changes and send it back – quickly. The process is not going well if you see the article again. I hate this, but I do understand. Every time I read it I will see something else to fix. The editor and the magazine (and you) need to get the issue to press and go on. The quality of response you send back is every bit as important as the effort you put into the original article. And remember, you’re article is part of a greater whole. Things like how code is displayed, figure captioning, and page count are decisions beyond the scope of what you’re doing. Getting the article ready for initial submission is a solo effort, but within the process of placing that article into the magazine in the best possible shape - you’re a team player.
You’re role on that team cannot be replaced. I like to imagine that an editor can improve my work by x%. Let’s say they can make it 25% better. Now if it begins as pure crap, well, they will make it 25% better crap. At the same time, I’m a technical person. I never match Stephen King’s prose or Rowling’s descriptions. There’s always room for improvement. If I take an extra day to self-edit, maybe have a friend read something over, what the editor starts with is good, add 25%, and I look pretty snazzy!
With respect, this is especially an issue for writing in a language other than your native tongue, generally that means non-native English speakers writing for an English language magazine. It’s not fair, and I am a total moron who can’t even read the work I’ve had translated into other languages, so who am I to talk? But your final article will be better – remember the editor can only do x% - if you have someone else edit and you review those edits for clarity before submitting the article.
It astounds me when I hear that people forget getting an article into a magazine is a team sport. If someone either feels protective of their words or they don’t bother to spend time in the review cycle to get things right, they are not thinking through the big picture. We don’t publish words, we publish ideas – get over the protective thing. If an editor says to me “this isn’t clear,” or “did you screw this up?” they save my butt and I totally appreciate it. They’ve found technical inconsistencies, and places my grammar was so bad I wound up saying something different than what I meant, and today even someplace where I mistyped a class name!
What I think King meant in his comment is this: Editors are not always right in what they suggest. But they are always right in showing what needs a second look and what can probably be better.
Writing this post has me thinking about some significant mentors in regards to writing – Claude Len Bullard who helped me understand while I was still in high school that communication matters, Robert Scoble who encouraged me to write my first articles, Deborah Kurata for putting me on the other side of the fence (I tech edited her first book and no editor has ever been as hard on me as I was on her), Don Kiely who explained the process, helped me remember what it meant to be a novice, and was there for me in tough times, Bill McCarthy for sometimes going over the exact wording of a difficult point in the guts of a language or CLR (OK, and sometimes actually explaining that point to me), Dan Appleman who encouraged me to write my book and step into my own light, and Patrick Meader who has been an awesome partner through years of writing, my kids for reminding me the most important things I write may not be about .NET, and of course, my parents and the Academy.