Ever wonder how the MSDN documentation gets written? Who are these people? What do they do? Where do they come from? Here are the answers to a few of those questions as I blog about a random day as a writer on the Silverlight User Education team.
Leave for work in my car. Yes, I’m one of those crazy early morning people but only because I have kids now. Before kids, I would roll in around 10am and you don’t even know how much I miss those days. Some days I carpool with my manager, Dawn. Soon, I will be walking a few blocks to catch the Connector (yay!) where I can work and commute in style.
I arrive bright and early before almost everyone except Cheryl who gets in sometime before the crack of dawn. After doing a brief scan of my email to see if anything exciting has happened in the last 12 hours, Cheryl and I (and sometimes Dawn) wander down to the cafeteria for a morning coffee/snack. Then back into our offices and the real work begins.
Check my tasks in outlook. This is where I personally keep a lot of my notes about what I’m working on, things I want to investigate more, things I need to follow-up on, etc. Usually a quick scan will inspire me to get started. Today, I’m working on a new topic for the Silverlight docs. I want it to be somewhere between a brief overview of all the top features and a tutorial. One stop shopping! We’ll see how it turns out. Everyone’s writing methodology is different. I tend to have a general idea and a rough outline and then I do stream of consciousness until I’m dry. Then I go back and see if I made any sense. Sometimes I have, which is great. It means I can clean it up, add some code, art, and links and toss it out for tech review and editing. Other times, it’s a mess and I have to figure out what to do with it.
Tired of writing. Sam, my officemate shows up. He’s supposed to be working from home today but is having connectivity problems which we discuss before he sticks his headphones on.
Need snack and some water. Head to the kitchen. Return to desk.
Can’t face writing anymore this morning. Time for some code. As I was writing I had a general idea of the code samples I wanted to put into the doc. Now, I need to write them and see if the whole thing holds together. I usually start with a code sample before I write, but this is an unsual topic and I wasn’t sure what I wanted to show until I wrote some ideas down.
Coding turned out to be super easy, so far. I was just doing basics like creating a control, adding an event handler and changing the color of a shape. Now I must “snippet” it. This involves adding tags that will allow the build to strip out the relevant bits of code and stick it into my document.
Yet! Its lunch time. My tummy is rumbling as my son would say. Luckily today is a fun day and I’m heading off campus for lunch with an old coworker.
Ok, I’m back, I’m full, I’m sleepy, and I have a meeting to go to. Bad, bad combination. Luckily, this is more of the 1 on 1 type meeting which is not as sleep inducing as say an all hands (large team meetings involving uncomfortable chairs, bad power point decks, and free food!).
Doc scrum. Meet in Wolf’s office for roundtable. This generally gets out of hand and we end up discussing some random issue that is interesting/annoying/challenging. Today’s topic ends up being the controls overviews. We’ve never managed to keep this meeting to the 15 min it’s scheduled for. Still, the topics from this meeting generally end up being something I’m glad that I know about later.
Done with meetings. Back to the real work. Still don’t want to go back to my new document from this morning, so I decide to follow-up on some issues. I need to talk to a guy about what his team thinks about quickstarts. Send random PM that I don’t know an email. Wait to hear back.
Need to create new art for some documents. Go into the tool, click on New Art. Arg! Something is broken in my tool and I cannot create new art. Send email to tools team. No one seems to know what is going on. Contemplate re-installing tools but really don’t want to. Must get Sam to make art request for me when he returns from meeting land.
Want to write code – time to find something new to work on. Let’s see, what to pick from – will I play with binding to collections, the converter parameter, ooh… How about Grid?! Ok, Grid it is. I still feel perplexed by grid. Let’s see if I can find the spec. Ahh, here it is. Now I must come up with an interesting yet fairly simple sample idea. Think, think, think. Ok, have idea, start writing code.
This is probably, for me, the most fun part of the job. Basically we get to research what the features actually do as opposed to what the spec claims. Luckily the Silverlight team has been generally great about producing features that are pretty close to how they were spec’d out. Still, specs rarely contain every little corner case and details of what happens when you are interacting with other features. So, it’s a little like research to feel that you have a good handle on any given topic. And since time is always a factor, you can’t spend too long playing with something before you sit down and start writing.
I feel like I have a decent handle on some of the APIs, so I open up the API pages and start adding some content.
“Joe” PM stops by to see how the UE world is going. I ask about the new features. Are they all still going in? Yes, in fact they are almost all checked in. Make mental note to install a new build soon. Ask “Joe” about documentation priorities. Make note of his opinion. Luckily, it matched up well with mine so I don’t have to overhaul my doc plans.
I’d better get going if I want to beat the traffic!
This is a fairly typical day for a Programming Writer. Sometimes we have a few more meetings; sometimes we have side projects related to doc builds, posting content on community sites, writing whitepapers for MSDN, thinking about content architecture, understanding search engines and discoverability, etc. If it’s related to helping customers use our products and our documentation, we spend time thinking about it.
Writers come from a variety of backgrounds. I was pursuing a PhD in Geophysics before I joined MSFT. But the people on our team have been developers, testers, PMs, scientists, writers, journalists and editors. If you like to write code, you want to help customers use great products, you love playing with the latest and greatest technology, and you like writing, you should think about being a Programming Writer. Specifically, if you think that sounds like fun and you think Silverlight is the best thing since sliced bread, then apply to our open position!