Sat Feb 05 2011

Yesterday I finished the final review on my first MSDN article. Surprised? Actually, I am too. I don't consider myself a good writer whatsoever.  I started blogging ( if you can call it that ) many many years ago just to force myself to write.  Honestly I'm terribly slow, can't spell, and one might think that English isn't even my native language. Regardless, I keep trying.

My article will hit the stands in April, but until then I wanted to do a brain dump of my experience before I call the finalizer on it. Let's start with some overall context about the article:

  • Title: Introduction to WebMatrix, so it's an "intro" article.
  • Published in MSDN Magazine
  • ~4k words or 13 pages ( in Microsoft Word )
  • 5 peer reviewers Sample code 2 review cycles with peers before the first draft was submitted
  • ~100 hours of work overall, spread over 3 weeks

Looking back at my experience here are some of my overall random thoughts of course in no particular order:

  • I started with a  brainstorm.  I am a mind map kinda guy so I used that to dump random thoughts and then organized from there.
  • I tried to pretend as if I was the reader and ask myself a few questions:
  • WHY would someone want to read this. *WHAT are you going to get out of reading it.
  • Would I WANT read it? Try to catch the reader in the first 2 paragraphs, otherwise they won't get to the rest. I had my wife read it.  She was INVAUABLE to my overall success.  She isn't a techie, but her perspective is very unique. If she can understand it, I know my communication skills were good.* Don't get hung up on order.  I "refactored" my article ~10 times. I think of it like code.  If it's factored right in the first place refactoring isn't a big deal.
  • Take it a section at a time.  Keeping the momentum going was essential for me.  It's really easy for me to get mired in something and then end up getting stalled.
  • Write you're abstract and sit on it. At least for me, in doing so I tend to think about the overall solution and have move of it figured out in my head before I get into the details.
  • Stay focused and watch the scope creep.  It's so easy to get carried away. Remember you only have a limited amount of space and time. Keep to the point and stay concise.* Write in active voice. I'm still learning what this really means.
  • If you're a loan author remember it's "I" not "We".
  • When you read your own article you will actually see words that are not there. The word 'the' is a good example.
  • Pick good reviewers. I look for a few things:
    *   Not afraid to hurt feelings, this is a place where honesty is very important.
    • Someone close to the topic.  Someone not close to the topic. Good at grammar. Don't be afraid to ask for help. I didn't do this alone by any stretch. The article changed drastically from the first draft to the last.  It's also much better.* An outline format works better for items like the steps a reader should take.

I am no expert and in fact I am a noob, but I hope this was at least somewhat helpful. I hope you check it out when it hits the stands, I would love any feedback.

Many thanks to @bsatrom, @davebost, @mark_nic, @sseely, and my wife.