An editor’s top six pet peeves

I’m sure many of you, our readers, have wondered what it takes to get an article published and what a good article looks like.

Well, that’s a pretty broad topic, but I can shed some light on the kinds of things that spell trouble for an article and things that absolutely drive this editor crazy.

1. Bulleted Lists

Let’s begin with bulleted lists. (I’ve had one of those weeks.) Twenty pages of bulleted lists do not an article make. That’s a great doc to take on camping trip, but in no way is a list an article. In fact, I’m not even sure it’s a good idea to begin a writing project with an outline. I know that’s not what we learned in elementary school, but then that’s also where we learned not to begin a sentence with but, and, or any conjunction. Writing in outlines limits the thought process. And that’s not all. When you write outline style, you tend to forget to go back and fill in the blanks. And it forces you to think not in the natural narrative way we think during conversation, but within the artificial category-driven confines of an outline. Imagine coming home from work to tell your significant others how your day went:

  • Drove to work.

  • Had chat with boss.

  • Discussed layoffs.

  • Came home.

That’s not a conversation and it’s not a story. Not to mention you dropped a bombshell with no explanation. Magazine writing tells a story. Though it might not appear to be the case, the sort of technical writing we do here is more than documentation. As a reader you need to take away more than just which step to follow first; you need to understand why things work the way they do. So, as a writer you need to write that part. You need to explain the whys and make the connections. You need to put yourself in the reader’s shoes. Ask yourself if the statement about layoffs deserves further explanation. This brings me to pet peeve number two: obscuring cause and effect.

2. Who’s on First?

Frequently I will encounter two facts sitting side-by-side in a sentence. It often seems as if there is some relationship between them, maybe even a causal one, but I just can’t tell. When I see this happen, I immediately wonder if the writer is being evasive and noncommittal or just doesn’t know the answer. The reader wonders too. Maybe the writer is simply a victim of passive voice. You’ll recognize passive voice when you see it. It’s writing that’s completely devoid of actors. Nobody is doing anything (like my house on a Saturday morning), yet lots of things are getting done (well, somewhere). The grass is being mowed. The car is being washed. The dog is being walked. These aren’t so bad, I guess. We can imagine who’s walking the dog. But what about the function that’s being called or the instance that’s being invoked? Or the service that’s being started?  In programming it’s nearly always the case that something caused something else which caused something else. Learning programming means understanding the chain of events. They’re vital.

It’s bad to keep readers in the dark about who’s doing what. It’s your job as a writer to be crystal clear on that and to make sure the reader doesn’t leave your sentence wondering who’s responsible for what.

3. Making Assumptions

There are so many assumptions writers make. One particularly annoying one I’ve seen a lot lately is the section subhead that does all the talking for the writer. I’ve seen writers make a statement in a section head and then never mention it again. He might allude to it, but never hits it head on. He might write something like the following header and then continue with the body of the text below it:

Clinton Wins Nomination

Now that that’s happened, pundits are wondering what’s next. 

Well, a sentence shouldn’t have to look up at his headline or subhead to learn what he’s about. Don’t assume the reader will want to either.

4. Muddled Thinking

Talking about a concept as if it has already been introduced is disorienting. A sentence like: “A newly elected member of the senate, Mary is fond of blue,” raises lots of questions. A dependent clause like “A newly elected member of the senate” is no place at all to introduce new information. The construction itself with the de-emphasis on the “newly elected” implies that the reader should already know this fact. The writer is already in a hurry to get past that part, so surely the reader knows it, or doesn’t need to. And it implies that Mary‘s political role has something to do with her color preferences. So, did it cause them? And why is the important part of the statement, the fact that Mary was elected to the senate, taking a back seat to her color preference? Because here, the color preference is certainly the point we’re driving home, although it shouldn’t be.

When people write this way, they don’t intend to say that being elected caused the color preference. They want to say that, hey, guess what, Mary was just elected to the senate. And by the way, she likes blue. But everything goes horribly wrong. Prioritize your thoughts, do not use dependent clauses this way, and properly introduce new facts as new facts. And while you’re at it, if your sentence implies that something caused something it didn’t cause, begin again.

5. The History Lesson

It can be difficult to decide how much background to present in an article. You may have lots of information at your disposal and believe that the reader will be better off having read it. But that’s not usually the case. Once you state your thesis at the beginning, it’s best to include only the historical information that’s absolutely necessary–in situations when the current state of affairs just makes no sense or any other time when the topics cannot be understood outside the context. But beyond that, too much history can bore the reader, look like padding, and cause the reader to abandon the article assuming that it will never live up to its promise.

6. What Diagram?

I’m not an artist myself, but I thought it would be fun to let you in on a little secret about some of the artwork we occasionally get. Take a look at the following diagram:


Brownie Sundaes

Interesting Political Discussions

NFL Football


Guess what? This is not a diagram. A diagram shows relationships between things. This does not. In fact, these things are not related at all but the reader will try with all his might to make the connection. Poor reader.

Yet another unnecessary diagram shows unidirectional flow from one entity to another. It simply causes more confusion than it’s worth.





There are many other topics I’d like to write about here to help anyone looking to clean up their submissions. So I’ll come back next week with more pet peeves (hopefully it will be a bad week).

In the meantime, I’d love to hear the editorial complaints you have in your role as reader. I’m sure they will help us refine our process as well, so please fill in the comments below.

And if you want to know what Editor-in-Chief Howard Dierking looks for when accepting a manuscript for publication, visit his post here.



Comments (12)

  1. A subscriber says:

    Completely off-topic.

    I just got my April issue of MSDN Magazine.

    It used to be protected by a plastic bag and without any kind of sticker on the front cover.  The sticker was glued to the plastic protection or on a white page inside the protection.

    It seems you have downgraded the protection (no more protection actually) and you have decided that the front cover doesn’t deserve any other attention than a big sticker with my address on it.  Bonus, the sticker is really hard to take off without damaging the front cover gggrrrr

    Maybe I’ll file a complaint… on the other side, should I stick to the online version (pun intended).

    I just got a renewal notice a week ago, interesting…

  2. Ben says:

    Who edits the MSDN .NET Class library documentation?

    I swear I see "who’s on first?" and "muddled thinking" all over the place.

    Not saying I could do better 😉

  3. Andy says:

    For blogging articles, would you recommend inline links or references at the end of the article more like a paper article?

  4. SamG says:

    I have a quick question about the new layout of the MSDN magazine. It seems to be a bit broken and more difficult to read and follow than the good, old format. Case in point, home page of the April 2008 magazine has a huge gap between "Columns" section title and the actual list of columns. It would be great to have a button "Apply previous CSS" on each page. To read your articles, I have to go to printer-friendly.

    I had the same issue with the sticker on the title page as someone who posted here before me. Generally, the most vicious stickers are applied to magazines and books across industry. Isn’t anyone thinking that those will damage the merchandise?

  5. Sam says:

    Now that we are talking about pet peeves, I have a question about printer-friendly article format. The new MSDNMAG layout does not expand figures in printer-friendly format which makes printing articles a bit inconvenient.

    Is there a way to print articles with all figures expanded? Or, better, is there a way to go back to the old layout

  6. MSDNMagazine says:

    Hi SamG

    I’ll pass your concerns to the appropriate people. We really do appreciate your feedback!


  7. MSDNMagazine says:

    Hi Andy

    I can only offer my personal preference, and that’s inline links, which provide more context.


  8. MSDNMagazine says:


    "Is there a way to print articles with all figures expanded? Or, better, is there a way to go back to the old layout"

    We’ll look into this. Thanks

  9. Peter says:

    Another printing problem is that the MSDN Magazine articles ( and others? ) no longer include the date the article was written or published.

  10. Ilya says:

    The printing of MSDN articles is a large concern for me – it also seems to be browser dependant. In Firefox, if you manaually expand the figures and then print, they appear on the printout.  In IE, if you expand all the figures and print, they are still collapsed.

    I’ve reached the point where I’m cutting and pasting the entire article into Word and print from there.

  11. MSDNMagazine says:

    Ilya, I will pass this feedback on to our web production team. Thanks.

  12. Xavier says:

    Thanks Ilya for the trick, I was looking for a solution to print the figures. Even if Firefox prints the figures, it has other problems. Copy/paste to Word is a better and satisfying workaround. I hope MSDNMag people will correct this point soon.