The only decent Help experience I’ve had with Microsoft developer tools involved my first experience with Microsoft developer tools. Maybe it’s the misty glasses of nostalgia, but from what I can so vividly remember, in Visual Basic 3, 4, 5 and 6 you could select anything, hit F1 and get a good rundown of whatever that thing was. This wasn’t spectacular, but it reminded me of good shoes: you don’t notice them.
Since then the general trend has been steadily downhill. The initial .NET versions of Visual Studio had a horrible Help experience where the thinking was that with all those palettes (I’m sorry, “tool windows”), what could go wrong if we added some more? Also, if we made it slow? Horribly so? The 2005 version cleaned up a bit by moving everything into a separate window; however, in a classical case of everything that Microsoft is doing that is wrong, unholy and “enterprise” showboating, this was in fact a “Document Explorer”. Also, still dog slow.
2008 — where we are today — is not as bad. The speed is up, which counts for a lot. But the language selector won’t remember your settings so apparently, I want that signature in VB (declaration), VB (usage), JScript.NET, J#, C++/CLI, F# and Brainfuck, and I want all of those variations to appear ahead of those in C#, and I want the syntactic differences to merely be hidden in the DOM rather than eliminated so that when I copy something, I get “string..::..Join” because hidden text is still included. And let’s not talk about help merging and one incorrectly run instance can force a full reinstall, or Microsoft’s 1999-era notion of “search is either fast and indexed on keywords or slow and a tax form”.
So, yeah. I wanted more for 2010, which is why I was hopeful when they ran a survey a year or so back asking for general feedback on the Help content and on the Help experience. Add to that the sudden outbreak of common sense when it was decided that they’re just going to zip a bunch of HTML files and an index and call it a day, and the promise of a new viewer written in WPF. (WPF itself isn’t important and sure as hell isn’t going to improve on a bad design, but it forces a rewrite (and thus a place for reconsidering the design) and is conducive to virtualization in, say, an index list or a big fucking table of contents tree.)
What we get instead is a small, fast, purpose built web server that runs in the tray and serves up everything in the default browser. Not only that, this is an actual, undoctored screenshot of some sample code:

Enough already.
- Opening everything in your default browser is a huge inconvenience, not to mention that the page is broken in Chrome.
- Searching brings up a separate page for hits instead of listing APIs in-line (suggest-style) and perhaps showing prose articles with summaries. Not only is it 2009, your company actually invented AJAX and claims to run a major search operation.
- The idea of a new viewer was thrown around until very recently. What happened to it? A viewer is the right way to go and the only way to implement bookmarks, table of contents and keyword indexes without needing to dirty the browser or half of the page (which will take time, space and resources to load).
- A small palette in Visual Studio to show more of the discussion around the method (exceptions thrown, more detailed information about what the method does; what you don’t see in Intellisense, basically) would be a great addition. As a popup, it sure was great in Netbeans several years back. Are you going to be shown up in user experience by a Java developer tool? (That’s not a “.NET vs Java” thing, that’s more of an “embarrassment” thing.)
- The cleaner MSDN Library variety that debuted a few months back was great except for the small-ish font and insistence on no scripts. That means that every signature shows up in every supported language; no hiding whatsoever. The Help version chooses a better, bigger font and stuffs the signatures in a “tab view”… which defaults to the wrong language (VB) and whose default tab you can’t change. Sigh.
There’s no shortage of good intentions. I’m willing to accept that VS2010′s Help may on the whole turn out a net win when compared to VS2008′s (for example, the new interface for downloading more documentation is much appreciated and the removal of the tedious and dangerous index merging shouldn’t be underestimated). But that doesn’t mean that there aren’t glaring flaws; flaws that have been obvious for years, and freshly minted ones that are just as glaring.
The fact that it’s taken so long to get it this right, even when this right is spectacularly wrong and incrementally worse in so many aspects, speaks lowly of Microsoft’s level of ambition and priorities. I know that that draws some snickers from the regular audience, but I’ve seen enough on other fronts to know that people inside Microsoft actually care about what they contribute. I would like nothing more than for Microsoft to please put some tools and resources in the hands of those who care about Help, instead of, like so many other times, not and saying they did.