It's a juggling act

  • [アーティクル]

If you are reading this blog post, it’s likely you saw Karl’s post highlighting some of the recent updates and improvements we’ve made to the existing Windows Forms documentation set. You might be wondering how we decided to make this particular set of changes and why we didn’t make more improvements. The following is a little insight into the job of a Programming Writer here at Microsoft and how we make these kinds of decisions.

First, we (the Programming Writers) have to figure out exactly what documentation improvements to make. We gather feedback on topics in a number of ways:

  • MSDN ratings and comments generated from the “Click to Rate and Give Feedback” tool at the top of each online topic
  • Bugs and suggestions filed on https://connect.microsoft.com/.
  • E-mail generated when you click the “Send comments about this topic” link at the bottom of topics that are installed on your local machine.

You’ll notice that we make decisions about which topics to change and improve almost exclusively based on feedback from our customers.

When making improvements to the documentation, we want to fix the most egregious errors first. For less serious changes, we want to target topics that are the most popular. Some questions we ask are:

  • How many customers are impacted by this issue?
  • What is the scope of the error? For example, is it technically inaccurate, or just not as descriptive as it could be?
  • How long will it take to fix?

A Programming Writer typically owns a large chunk of legacy content as well as a documentation set for the next product release. This means that not only are we multifaceted programmers and writers, we also must be skilled at managing multiple projects and deadlines. I say multifaceted, because before our team recently hired a couple of new folks; I owned legacy topics around data binding, graphics, visual styles, user input, various Windows Forms controls, and the list goes on. It’s up to me to be an expert in all of those content areas, whether or not I wrote the content originally, so that I can intelligently respond to customer feedback and make decisions about updating the topics related to these features. In addition—and this is where the project management comes in—I am also typically ramping up or writing content for my new features for the next release of the product. Don’t get me wrong; I am not complaining. I think I can speak for most Programming Writers when I say I love the variety and continuous challenges of my position.

Hopefully this explains why you might not get as many documentation updates as often as you would like. As Karl mentions, to make sure you are getting the latest updates, you should always check the online version of the documentation. Also, there are a couple of other things you can do. If you have a problem with your code, make sure and use the MSDN forums as a means to get your questions answered. These forums are monitored by experts inside and outside of Microsoft and they have a lot of knowledge to spread around. Secondly, and on the topic of spreading knowledge, if you have a better code example than the official documentation, you can provide some insightful tips about a particular API, or have other improvements to the existing content, make sure and check out the Community Content section at the bottom of each online document. This section allows you, the customer, to suggest changes and additions in a wiki-like format.

Help us make the best changes by continuing to provide ratings and comments on the documentation in any of the ways I mentioned previously. Tell us specifically what can be improved and why, and we’ll do our best to act on it.

Comments

  • Anonymous
    April 25, 2007
    The comment has been removed