Wednesday, September 15, 2004

MSDN Alpha Available

For the past two years, I've been working on a complete overhaul of the MSDN publishing system. Tim Ewald was one of the principal forces behind this effort, but there were plenty of other really smart people involved, too: I am not at all kidding to say that merely keeping up with them was difficult.

Well, quietly, last week, the first publicly accessible incarnation of what we've been doing went up at We weren't supposed to spill the beans yet, but Jenfeng Zhang broke the news, and we've gotten the go-ahead to blog about it.

This is a complete rewrite of the MSDN publishing engine, from the ground up; we started with zero code. Of course, you'll notice that the look-and-feel of the docs remains largely the same: most of the changes lurk beneath the surface. For example, the entire publishing process is now deeply XML-oriented. Content comes in as XML, gets processed as XML, gets stored as XML, and even gets rendered as XHTML. This is going to allow MSDN to introduce a lot more services around their extremely rich set of documents...just wait and see.

Of course, some of the changes are visible, too. You've probably noticed that the URLs are vastly improved. For example, you can now surf to to get documentation about the new GZipStream class. We call this an alias. The “real” URL for this document is, where “zs4f0x23” is what we call the short ID for the doc. We did a lot of work to make sure that this identifier is stable, so that URLs won't break.

Even though I've now finished my involvement with the project, I'm pretty excited about this release. It is the most significant (largest scale) piece of software I've ever shipped, and a lot of my code is running in it. Not that I was the primary developer, but there will be MSDN devs maintaining my code for quite some time to come. I learned a ton, not only from Tim, but from a woman named Kim Wolk without whom this software literally never would have shipped. She hates it when I mention her name, but I think she deserves more credit on this release than any other single person on the team, and it would be a crime if no one came out and pointed her out as the hero of this project.

So go give it a test drive and let MSDN know what you think. It's only an alpha, so don't be too surprised if something breaks or doesn't work the way you'd expect, but take my word for it: this is a huge step forward for MSDN, and by extension, for the developers that rely on it.


  1. For me it's great. Wihtout those tree control it work much faster. Earlier MyIE (which I use) was blocked for time of page load. I don't know why.

    Also at last, it's possible to save printable version on my computer.

    Nice work :-)

  2. Thanks! Generating the TOC was actually very, very complicated - I spent a lot of time working on the processing that creates that maps out the left-hand hierarchical navigation. And the problem still isn't solved in a general way.

  3. Ahh, sorry for stealing the thunder:) I just can't help spead the excitement.

  4. Damn - EXCELLENT :) Looks very nice, and I can only assume that its very nice behind the scenes :)

    I especially like the LACK of use of frames - that was my biggest problem with the current one.

    Now, any chance of having SOME form of static version that I can put on an intranet server..... ;-) Even just for the namespaces....

  5. Oh, and - any chance of getting someone to write some msdn articles on how it all works behind the scenes. I think it would be very interesting and helpful for a lot of people.



  6. Jenfeng: no harm, no foul - the news had to get out sooner or later.

    Nic: the debate over frames was a long and tough one. Fundamentally, the issue was, "How do we preserve a useful URL in the nav bar without having to reload the tree every time?"

    As far as MSDN articles, that seems like a great idea. Unfortunately, I have no control over what happens. I'll pass the idea along, though.

  7. From Craig: "How do we preserve a useful URL in the nav bar without having to reload the tree every time?"

    By not using frames ;-) I can see what you would have this problem tho - there are a LOT of tree nodes in there. Maybe some other method would be good - eg, putting a search as the main navigation option, and being able to search for specific things, eg a class/namespace/property/article etc. Of course, with not having frames, google should now be able to do a much better job of indexing it ;-)

    Anyway, cheers for the feed back and the view of the new stuff :) Look'in DAMN EXCELLENT :) ('cos lookin' good just doesn't cover it)

  8. Thanks! I'll pass along your comments.

  9. What are the plans for versioning with the stable URLs? Presumably if I navigate to .../System.IO.FileInfo I get the docs for FileInfo in the then-current version of the framework. If I need to find out the behaviour in an older version of the framework (say, the current version is Orcas and I'm still on Whidbey), will there be a stable URL for that?

    For example it might be useful to rule that although .../ClassName.aspx goes to the current version, .../20/ClassName.aspx always goes to the Whidbey version. Just a suggestion.

    Nice touch that you don't even have to enter the .aspx extension by the way.

  10. On versioning, I should note that aliases are not intended to be "stable". System.IO.FileInfo can point to anything, and will probably be set up to point to the latest version.

    There is a mechanism for versioning built in to the URL scheme. I no longer have access to the code, so I can't remember exactly what it is (we changed it a lot right towards the end), but there's something like a query string parameter that you can specify to say which one you want. Similarly for language.

  11. Thanks for all the hard work, Craig!

  12. Two things wrong with one of the nav's css classes. I've snipped the non-relevant styles.

    .TocPane a {


    border: solid 1px F0F0F0;


    Can not set height on an inline element(!!), and a bit of dyslexia on the border...need to flip the size and style.

    This is what they should be changed to:

    .TocPane a {

    display: block;

    border: 1px solid #F0F0F0;


    These two lines are currently breaking every browser except IE/Win. How IE is even managing to not break is what boggles me.

  13. Thanks - I've passed your comments along to the team.

    Oh, and it wasn't my fault. :)

  14. Actually, the aliases should be stable and use the same versioning technique used for short ids. That is, you'll be able to specify a "version independent" URL which takes you to the latest doc or a "version dependent" URL that takes you to a specific version. There's only one version in the system right now, so this is not yet an issue.


  15. One major request of mine is to allow the left menu and the top MSDN header bar to be collapsed for a "clean" view. When opening MSDN on a small screen (like the 800x600 screens we use for some embedded platforms), the nav/menu bars end up taking almost 40% of the screen.

  16. At first glance this looks very nice, but it's a little bit broken in Mozilla Firefox.

    Firstly, the highlight boxes around the TOC content overlap when a line is wrapped (which is a lot in Fx). This is what red_avni was talking about, and I can confirm his fix.

    More importantly, the style used for code blocks isn't working properly. The whole code sample is running together as a single (wrapped) line.

    It looks like the culprit is :



    /* margin: 0px 0px 0px 0px; */





    Why is that "white-space:normal;"? Shouldn't it be "pre"? I used the DOM Inspector to change it to "pre" and it all displayed fine.

    Good work, though. Like I say, this looks nice. Is any of the legacy content going to be migrated?

  17. Nick: cool tool. :)

    Dmitri: I'm not quite sure how you think an *ex* contractor is going to help you get work at MSDN. :) But I've passed your comments along to the team.

    James: thanks - I've passed your comments along to the team.

    As you can see, the site still needs work, like any alpha. Your comments are very helpful in helping them find what's broken!

  18. Sanjay: thanks I've passed your suggestion along to the team.

  19. Craig, who said anything about working at MSDN? I am happy where I am, thank you very much. I was just trying to help out fellow colleagues.

  20. Sorry Dmitri! I misunderstood your altruistic intents. My apologies. Like I said, I've passed along your comments to the team.