Dr. Dobb's | MSDN Wiki: What's Up?

MSDN Wiki: What's Up?

Microsoft to provide documentation power to the people

November 14, 2006
URL:http://www.drdobbs.com/windows/msdn-wiki-whats-up/194300481

Scott Swigart is a consultant specializing in convergence of current and emerging technologies. Scott can be contacted at [email protected].

DDJ: I'm familiar with what MSDN Wiki is, but I don't know that the world at large is. Could I get you to start off with an introduction to what MSDN Wiki is, and maybe even more importantly, why MSDN Wiki is?

Molly: For the last year or so, my team has been looking at different ways that we can allow the community to expand and enhance the product documentation that we supply. What we've done on the current site is build a wiki around the MSDN documentation. People can add community content to the end of a page and put in tags, examples, tips and tricks, and other information that relates to the products, information that we didn't cover in the original documentation.

Translation is the second part of our project. MSDN publishes machine-translated content to our translation wiki site and then allows people in the community to make changes that improve the translation. In that case, people can make their edits in-line in the documentation.

DDJ: In other words, there are two goals. One of them is to take the MSDN content, and let the community localize it to a lot more languages than would otherwise be feasible, and the other goal is for the community to have the opportunity to expand the documentation that ships with the product and shows up on MSDN site. Is that an accurate summary?

Rob: Yes, it is.

DDJ: So, how's it going? You've launched this now, and the community can contribute content and do translations. How are you seeing the community engage at this initial point?

Molly: The response so far has been excellent. Our English site has been live since early June, and we've had 1700 edits covering close to 1000 topics. The quality of information that we've gotten has been really high, and we haven't had a lot of problems with vandalism, or those kinds of things, which is great. The feedback that we've gotten from people has been really positive so far. We've noticed a lot of interesting things about how people interact on the site. They seem more apt to create new content blocks rather than editing somebody else's content, for example.

DDJ: I didn't realize there had been 1700 edits, that's great. It seems to me that one of the things that prevents vandalism, and that makes this a little bit different from a traditional Wiki, is that you can't really modify the MSDN documentation. The content that you contribute is more like comments that get appended onto the end of the page, but you can't edit the core documents themselves.

Molly: Right, we don't have to worry about people touching the Microsoft content directly. Also, several of our top contributors who were on the site anyway have become moderators. They have the ability, if they do see something that's inappropriate, to get to it right away.

DDJ: So in other words, people in the community who have been really active in contributing to the success of the site have been given a little more authority in helping ensure that it keeps going in a good direction?

Molly: Right, exactly.

DDJ: Is there a point at which the MSDN Wiki will replace the traditional MSDN documentation? I know that if you're in Visual Studio right now and you hit F1 to go into the help, it's not the MSDN Wiki that you go to. Currently, the MSDN Wiki is a copy of the MSDN documentation, and it's in a different location on the Web.

Rob: Today, MDSN Wiki is a complete duplication of all the Visual Studio 2005 product documentation. That's an artifact of it being developed in its own little sandbox. Today, if you do a search on Windows Live or your favorite Web search engine, you wouldn't find any of the MSDN Wiki content. We've purposely blocked robots, spiders, and so on, because we'd end up getting duplicate hits on every single piece of content. But, the goal is to merge those two into the same content.

It's not a matter of the Wiki replacing the existing online content, or the online content going away. Basically it's just making one set available that will let search engines index it, and link to actual community content on MSDN Wiki. The success of MSDN Wiki to date is entirely the result of word of mouth and people blogging about it, because you can't find it by searching for it. In just the last two months, the number of people going out of their way to put the content on the Wiki is pretty remarkable. Once that content starts showing up in search engine results we're going to see a spike in the amount of contributions happening to MSDN Wiki.

DDJ: Yeah, I could imagine that you might see a 5 or 10 X increase in contributions. Based on what you're saying, right now if you don't already know it's there, you're not likely to find it. That's about to change.

Rob: Right.

DDJ: You mentioned that you're not currently seeing problems with vandalism, but again, when it goes public, you might see those kinds of problems appear.

Rob: Right, and that's part of the risk of having a publicly accessible Wiki. It just goes with the territory.

DDJ: Have you disclosed any time frame for when the MSDN docs switch over to MSDN Wiki?

Molly: The current plan is that in December we will have the current MSDN Wiki English content merged into with the main MSDN Library. From there, the functionality will sort of graduate to other documentations sets. I've gotten a lot of questions about, "When can I have this?" Basically it's all coming gradually starting in December.

DDJ: Right now, the contributors are almost all insiders, people who know it's there. Then, it will go public and the Visual Studio/.NET Framework docs will include the "Community Content". Assuming that's successful, and as you iron out any problems, you'll expand it out to more and more document sets, until, I'm guessing, that this is just the way Microsoft does documentation going forward? Is that too broad of a swath?

Rob: No, it's actually fairly accurate. The other thing that's going on in parallel with all this is that MSDN and TechNet are both undergoing a transition in the publication system that they're using. People are probably familiar with the MSDN2 version of the library. That is a version of those product documents published in the new publishing system. MSDN Wiki uses the new publishing system that MSDN2 uses, so the only content that we can provide the Wiki for today is content that exists in that new publishing system, and that's actually what limits which document sets can be part of MSDN Wiki.

DDJ: I see, so until you get more document sets running on that engine, you can't really Wiki-enable them. Once you do, it becomes almost automatic to provide the Wiki functionality.

Rob: Right, there's basically nothing that blocks us technically at that point.

DDJ: One of the things that's been the biggest surprise to me is who the contributors are. When I looked at the Wiki at the very beginning, I thought, "This is great. This will really let the community contribute tips and tricks, and lesser known facts. One of the things I found surprising is that the Wiki is almost a back door for Microsoft employees to build out the docs. In other words, I'll see a post from somebody who identifies themselves as a Microsoft employee, and they're posting really low-level information about exceptions that might be thrown, or why something is a certain way in the Framework, or even where they'll point out that in certain cases the actual documentation might not be accurate. When I look at it, I think, "Is this the person who actually wrote this particular piece of the API?" because the poster has such deep knowledge.

Molly: We've been very pleased with the amount and the quality of the information that Microsoft people have contributed. When we went through and looked at the contributors list, we found that the authors for the new content are heavily skewed towards Microsoft people right now. I think a big chunk of that is because of the fact that we have heavily promoted the Wiki among the developers at Microsoft. We have pretty good recognition within the company, and not quite as good outside of the company yet. A lot of the people developing Visual Studio and the .NET Framework are really excited about the Wiki. They have knowledge about things at a really low level, and Microsoft doesn't have the resources to capture that level of detail in the product documentation. This gives them a way to provide that information along with the documentation.

DDJ: Going in, I don't know that anybody foresaw Microsoft people would post so much "community" content, but it's a really nice side effect. In some cases you feel like there's a direct link between a developer who wrote a piece of the API, and the community out there that's trying to use it.

There's another thing that you've done that I really like; I might be one of the few people who takes advantage of this, but you expose an RSS feed, so if you want to see every piece of content that gets posted by the community, you can subscribe to that as a feed.

Rob: You've almost got to have it. Even though today, it's only the Visual Studio 2005 product documentation that's in the Wiki, that's still a huge body of content. And to try to keep apprised of everything that's changing in MSDN Wiki, the only other option would be to go browsing through it every day to see what's new. The RSS really gives you an opportunity to be constantly aware of what's going on. It also helps us because we get to see changes as they happen. That helps with the moderation process. It allows us to get an early jump on things if something goes awry.

DDJ: For me, as a developer, I look at it maybe once or twice a week, just to see what's new. Invariably there'll be some really good nugget of information in there that I'm glad I read. Going forward, I'd be curious to find out what you're thinking about for some of the near-term enhancements based on the usage that you've seen so far, and some of the feedback that you've gotten so far.

Molly: In the December time frame we are merging the community content back into the main MSDN Library. Two other areas that we're focusing on are the editing experience and tagging. The editing team has done some incredible work on their rendering system, and so all the editing will be inline. In content blocks, there won't be any more pop-up windows, or that kind of thing. The other thing that they're looking at is tagging, to allow people to add tags to categorize things in the community content. We're looking at ways that we can expose categorized lists in the RSS as well.

DDJ: So you might be able to customize your RSS feed so that it's just serving up things that are tagged as asp.net or Windows forms, or XML, or something like that?

Molly: Right, exactly.

Rob: Or a particular class library. You might want to be able to be a lead contributor in a certain area of the documents.

DDJ: So in other words, maybe you'd be able to subscribe to an RSS feed based off a namespace?

Molly: That's something we'd really, really like to have. I don't think we'll have that in December, but we're looking at how we can do that in the future, because that's something that people, in particular the Microsoft people who have been contributing a lot, really want. They want to say, "I really only care about that stuff, so I can subscribe to the namespace, and ignore everything else."

DDJ: I know Microsoft is pretty proactive about tasking its product managers with hanging out in the newsgroups, and things like that. It would seem logical that if you own System.Windows.Forms, you might want to keep an eye on that section of the Wiki.

Rob: You see the same sort of thing happen in Wikipedia. There are certain topics in Wikipedia that people live and breathe by. Within 30 seconds of an edit happening to it, they're on there, either fixing something or correcting an inaccuracy. You might see the same association take place here. We have internal Microsoft people that are adding to the Wiki. 99 times out of 100, they are probably adding to the section of the Wiki that relates to their day job.

DDJ: Right. And that's the beauty of it. One other thing, and I hate to say this but I know it's true, a lot of the community that contributes to things like this does so for a certain amount of ego gratification. Maybe a better way to say that would be that people are contributing to make a name for them self, and get established as an experts on certain topics. What kind of facilities are there in the Wiki that reward people for making lots of valuable contributions?

Molly: That's a good question. Right now on the MSDN Wiki home page we list recent contributions and top contributors. This page gets a lot of traffic so being listed on it is a good way for contributors to gain name recognition with site visitors. The other thing that contributors really like is that when you register on the site you get a profile page. Currently, we don't let you enter a lot of information on the profile page. Basically you can enter a URL. But it's a place where visitors can go and see all the contributions from any person who has added content to the site. So that's something that we're investigating how we can expand this in the future. What we'd really like to do is see how we can extend some of these profiles across different MSDN sites. Right now, you might be contributing on the forums, on the Wiki, and on the feedback center. Basically, they're all separate right now. We're looking at how we can create a profile across the MSDN sites that will include bios and other things that let people promote themselves.

There's something you mentioned earlier in regards to the Microsoft contributors that I hadn't considered. I know who these contributors are, and what team they're on, and what product they're on because I'm also internal. But that information isn't available to the readers. I'm wondering what we can do to make it really obvious that this person is an expert working on the product, to let you know this is a person you can trust.

DDJ: Yeah, it's just a pretty typical feature of forums, and MSDN Wiki has a little bit of a forum feel. I could see somebody getting rated as being a top poster. They either post a lot, or their posts are highly rated by other readers, or both. Obviously all this stuff takes time to implement. But it seems to me that that would increase the popularity and encourage more and better contributions to the Wiki.

Another thing I've seen is that somebody will make the same post in 20 different areas in the docs because it's applicable to a bunch of API's under a given class, or a bunch of overloads for a given function, or something like that. Has there been much thought into letting a user make a single post that applies to more than one entry in the docs?

Molly: Yes, that's something we've talked about a lot because, like you said, there are a lot of places where the current contributors have added basically the same thing to a lot of topics. The contributor has to decide, "OK, do I want to go and copy this to all the different topics or put it in one place and encourage readers to go to that place from other topics." The problem is that if you want to update that content, you have to go and update it in multiple places, or the people reading the content need to click around to get to the actual information. We're looking at ways that we can let people add one content block that they can associate with multiple topics. For example, with overloaded methods you might want to provide the same content for every overload. We're looking at that kind of thing. We know that this is something, based on the activity we've seen on the current site, that will be useful for a lot of people. But I'm not sure when we're going to do it. It might not be until next version.

DDJ: Okay.

Rob: It's not easy.

DDJ: Sure, you don't want somebody to go to the root of the documents and say this piece of spam applies to everything. And at the same time you don't want people to have to repeat the same post literally 15 times, and have each instance stored as a separate post.

Rob: It's basically a bulk update. Maybe a bulk update is something that a moderator could do. Or, if you're on some trusted level on MSDN Wiki, you're able to do a bulk update. There's a million ways you could probably slice it.

DDJ: So far I've been very happy with the Wiki. I think the concept is great. I'm a user of it. It's nice just to be able to go in and post information that shows up right in the docs. It's also great just to sit on the feed and glean the things that other people have been willing to share. I hope nothing but unbelievable success for the project. I think it addresses one of the most common complaints about the docs, which is that they're sometimes wrong, or they're often incomplete. There are sections of the framework that are practically undocumented. This lets people in the community just treat what Microsoft puts out there as a seed. The community can grow the content as much as they want from that point.

Rob: Yes, I fully agree.

Rob: One of the things that really drove home how successful this could be was when I started seeing people from whom I buy books posting content on the Wiki. For example, Dan Appleman recently contributed content to MSDNWiki. For anyone who's a Visual Basic developer, Dan Appleman's books are right up there in the pantheon of books you've probably read.

DDJ: Like I said, when Google can go through and index that stuff, it will be a great way for people to get their name out there. When you think of the top 200 book authors, you would hope that they would be contributors. And it probably wouldn't hurt their book sales one bit.

Rob: There's also a potential to expose an API for MSDN Wiki. Think about the kind of mash ups you could make.

DDJ: Okay, so that's an interesting concept. Right now you expose an RSS feed. But you're thinking about exposing a full service on top of the Wiki?

Molly: Yeah, actually MSDN has Web services that they're exposing right now that you can use to pull content and TOC structure. They're planning to expand those to include the community content. I'm not quite sure what the format will be, if you'll get both Microsoft content and community content all together or if you could pull one or the other. But it's something we have in the works.

DDJ: That's great. You talked about mash ups. I don't know if there's an easy way to do this, but think about the way a lot of content sharing sites make it easy for you to drop in their content without having to copy and paste. Think of YouTube and how easy it makes it to take one of their videos and embed it in your site, or on your blog, or whatever. It would be nice if there was just a little snippet of HTML you could throw into your blog that would suck in a piece of community content that was ultimately being pulled from the Wiki. It would be easy for you to include without a copy and paste of it.

Molly: That's interesting. That's one we haven't thought about. I can see people, if they're blogging about something in the Wiki, just pulling it in that way. That would be cool.

DDJ: Yeah. You could surface a little link and have it pull from the Wiki. So you're able to see how much traffic certain community posts get. That seems like another output that would be directly useful to a contributor to the Wiki. As Microsoft you would probably certainly want to know where the hot spots in the Wiki are. You'd want to see what community content people are reading about. Maybe those things are candidates for articles, or feedback for the product team.

Molly: We have an internal reporting site where Microsoft content authors can review information and feedback that's coming through MSDN, and now MSDN Wiki, about topics that they own. Just yesterday evening we launched an update that adds information about community content contributions to this site. We haven't thought as much about how to expose that information externally. But it is an interesting thing to think about. I can see how it would be interesting for people to see what community content is getting the most traffic.

DDJ: I've already seen places in the Wiki where a discussion starts. Where somebody will say, "Don't implement this interface." And somebody will say, "You absolutely should implement this interface." I can imagine that kind of thing will happen a lot when it's just part of the docs. You'll really end up with discussion threads in the comments. And it would be kind of interesting, as a user, to see what was hot.

Rob: There's a good example what could've happened, about a year ago. There was a flap over a help topic that provided guidelines regarding test-driven development (TDD). For those who were proponents of TDD, it kind of flew in the face of what they felt TDD was about. There was a lot of discussion that took place away from the article. You had to happen upon somebody's blog, or Slashdot, or wherever the conversation was going on. The conversation wasn't going on where the content lived. If you were new to TDD and read the help topic, you wouldn't know the content was held in contention. If you stumbled upon the argument without the context of the help topic, you had to wonder, "What is this content that they're talking about?" You'd had to follow through to where somebody linked to it, jump over to that page, and read the content. Then you had to jump back over to where the conversation was taking place and try to join in with the conversation. It would have been very cool if that conversation would have taken place right there in line with the documentation.

DDJ: So anything you eventually find under MSDN, whether it's an article or whatever. You'd be able to have this sort of community content section that shows up at the bottom of it?

Molly: Potentially. Technically anybody who publishes content on MSDN will be able to add the community content section to their pages. Teams will be able to decide whether they want to add it to their entire documentation set and to and individual white papers and articles.

DDJ: And I would imagine that there will be a certain amount of pressure to do that from the community.

Molly: Yes, we've gotten lots of questions from people who are using the current site about when the documentation for other products will support community content.

DDJ: If people have suggestions and feedback, should the post them to Microsoft Connect?

Molly: Actually that's the best place to post suggestions because they come directly to our internal bug database. They definitely get looked at that way.

DDJ: Thanks for taking the time to chat.