Tim Sullivan, one of the fabulous software development engineers on my team, bares all in this review of proposed changes to the Visual Studio help system.  Folks, when Microsoft says it intends to be more transparent in the design and development of software, Microsoft means it.  Tim gets you as close to the feature development action as you can get without attracting some really sticky bugs.  Here are few quotes from Tim's Opus and a bit of commentary from your's truly:

"Help and Community are getting a lot of attention in Whidbey." -- Show me the money!

"Unfortunately, due to the sheer number of help topics in MSDN and a few scheduling and organizational issues, I can pretty much guarantee that a number of help topics will still be sub-par when we ship Whidbey." -- Self-supporting communities of like-minded developers will continue to be an invaluable resource into the foreseeable future.  We're raging against the machine to pump out code examples but those .NET Framework fools (Brad Abrams, Don Box, et al) are freakin' prolific.  No rest for the weary though since companies, including Microsoft, continue to unveil new .NET languages.  Seriously, I love to troll our international product feedback reports for fish like this (not an actual quote but similar to real ones), "Help would be *perfect* if the existing topic for the System.Math.Cos function was available in Swedish and included J# and COBOL .NET examples, especially ones related to accounting." Wouldn't it though?

"Also, make sure to use the 'send feedback' links whenever you find an MSDN topic that's not to your liking; those bits of feedback are all read by actual people and they result in bug entries that someone will be responsible for fixing." -- SEND FEEDBACK! I'm one of those actual people and your actual feedback actually helps me help you better.  It's a virtuous cycle. You can even mention that I sent you, if you want. ;-)

"You'll also have the option of going online for F1.  This will have 2 beneficial effects: First, you'll get the very newest help topics." -- Personally, I disagree with this feature and encourage you to stick to the offline, on-disk help topics. In my opinion, it's a mistake to point users to two versions of a help topic without giving them more information and context. In particular, users should be able to determine which topic is more up to date, the online version or the offline version. As this F1 feature is currently implemented, I don't think there's a way to do so.

"How do I... -- This is an entirely new view into the help system. It's a hierarchical organization of common tasks a developer is likely to encounter. Each developer segment (VB, C#, Web, etc.) will have its own hierarchy containing roughly 200-400 tasks. Each task will contain carefully reviewed editorial text along with sample code that can be copied and pasted into the VS editor. The documentation teams have been collecting user feedback to help determine which tasks to include in the hierarchies. If you have ideas for tasks you'd like to see in a How do I... page, let me know and I'll pass them along to the right people.  You can think of How Do I... as a hand-picked, carefully designed subset of the Table of Contents." -- Sweet.  I could have used this when I was learning about XPath.

"Inclusion of Community content:

Going online to access MSDN content has its benefits, but the biggest win in searching online is really the ability to access living content.  If you look at some of the fantastic work that Community-based web sites like .Net247, CodeProject, ASP.Net, and others have done, it's clear that static content published to the web can never be as rich as content that is provided by members of the developer community. " -- You said it, brother. The more community, the merrier.

"Don't get me wrong, MSDN's API reference is obviously important.  But if you open that content up to be annotated and extended by people in the community, then it becomes a much more powerful resource." -- Timmaaayyy, NOW you're talkin'.

"MSDN's code snippet looks very comprehensive, but .Net 247's page provides so much more variety, and it's directly linked to a forum where I can ask questions about the code and interact with the code authors or other forum members.  The experience at the Community-based site is much richer because the content is far more dynamic and because I can interact instead of just reading." -- Community Community Community Community !

"So how does this apply to VS?  In Whidbey we have partnered with a number of Community sites that will allow MS to aggregate and search their content from the VS client. " -- That's right, we're baking community into the Visual Studio IDE.

In response to reader comments Tim writes:

"Chris) (paraphrasing) How will all this community stuff show up in the IDE?

Newsgroups, forums, and web sites that are part of the CodeWise program will come back as part of Community search results. Annotations will be an intrinsic part of the online versions of the topics. Blogs and RSS feeds are on the radar, but we don't have a good story for them yet. If you have ideas on how you'd like to see them integrated, let me know
" -- Hm. Allow me to qualify... Annotations may be an intrinsic part of the online versions of topics. As much as I, like all developers, love the MSDN Annotations feature, it's not a done deal yet.  They're still testing the concept.

Blogs and RSS feeds?  Heck Tim, don’t hesitate. Don’t waffle. Don’t vacillate. Visual Studio should support both the creation and consumption of RSS feeds. A native newsreader should be plugged into the IDE and you should be able to publish stuff (like build errors) to an RSS feed using automation.

This posting is provided "AS IS" with no warranties, and confers no rights.