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. http://www.dailywritingtips.com/active-voice/
- 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.