An early release of MSDN2 went live two weeks ago today. There have been quite a few posts about it, most of them very positive. The site, which contains only the Whidbey beta 1 documentation, is the first widely available use of our new online delivery and rendering infrastructure, called MTPS (MSDN/TechNet Publishing System). Unlike the main MSDN Library, the content in MTPS is delivered directly from the UE team that wrote it as individual XML topics, NOT decompiled from the offline help package (a .HxS file). This marks a big step forward for MSDN because it is the first step away from a very expensive process that involves taking ~1500 .HxS files containing hundreds of thousands of HTML files and modifying them to build the MSDN Web site. It is changes in the structure of these files that have changed MSDN URLs in the past, leading to tons of frustration for everyone.
The MSDN2 feature that's getting the most content is the ability to use a managed API name as a URL. While that is a cool feature, it's really only one aspect of a new URL model that's designed to keep links from breaking. Specifically, each topic is now identified using an id that is held constant across minor revisions and major versions of a topic; and also across locales. The id has three forms: a GUID for decentralized authoring (sometimes cooked up by MSDN based on a locally unique identifier in a topic), a short id and, optionally an alias. Aliases are used when a piece of content has a for well-known (e.g., a TechNet KB#) or inferrable name (a managed - and someday a native - API name). These values can be used interchangeably. For instance, these URLs reference the same topic:
http://msdn2.microsoft.com/library/system.xml.xmlreader.aspx
http://msdn2.microsoft.com/library/b8a5e1s5.aspx
The last token in the URL path identifies a topic, the left-hand of the URL identifies the context in which it's seen. The context piece MAY be used by a site to decide what do display in it's chrome. Because these two pieces are seperate, you can write URLs that make arbitrary combinations of the two, like this (note that the CSS won't work right, but the topic is displayed):
http://msdn2.microsoft.com/library/foo/bar/system.xml.xmlreader.aspx
It is an essential part of this model, then, that all topic ids are usable everywhere. That is, all content exists in all locations in a context, or in multiple contexts. That enables us to surface the same information in multiple sites, with multiple organizations, allowing us to tailor information delivery to specific customer needs, as with the Library and the various Dev Centers (these share some content today, but it's a hack).
This also means that, even if a DNS name or vroot goes away, you should ultimately be able to take the last token of a URL you know, append it to a wellknown base URL (ultimately, it should be msdn2.microsoft.com) and get the right content. Further, our 404 handling code should be smart enough to do that for you. We aren't there yet, but that's where we're headed.
Now, more about aliases. Here are some comments I posted on Junfeng's blog when he broke the news that we were live (about 2/3 of the way down you'll see my favorite aliasing feature, which is the ability to access the list of a types members by appending _members to the type name):
The URL alias mechanism is a new feature we added for this early release of our new online infrastructure. It's designed to work for every managed API page, but it isn't fully implemented yet. Here are some observations:
It will work for namespaces as long as they have a '.' in them. So it won't work for the System, Microsoft, etc. namespaces. This is a bug that will be fixed.
It should work for all class names. It will work for *SOME* property and method names. We tried to get all of them working, but ran into some issues, so we had to drop some for this early release. The plan is to make it work for all fields/properties/methods, including overloads. Note that you have to reference the member on it's defining type. Inherited members are not exposed with an alias on the derived type unless they are overridden. This is simply the nature of the doc structure.
You can also get to the list of methods, properties, fields or all members, but appending the appropriate value, like this:
http://msdn2.microsoft.com/library/System.Reflection.Assembly_Members
As Chris noted, the .aspx is optional.
Finally, the database behind this is not yet optimized for this sort of access. That will happen in a future release. So be patient if alias resolution takes a little longer than short id based lookups.
Finally, note one other feature. The URL's you navigate to use short ids instead of file paths. This is the first concrete step toward keeping API URLs stable over time.
Finally, I have to mention the new model we used for tree navigation of the site. This is a big change for a site whose customers routinely tell us that they use this resource everyday and they don't want us to change it. We went this way because it let us avoid frames, reflect the current page's URL in the address bar, and it's pretty fast; all of which people have asked for for a long time. The other interesting issue is scale. The current Library has many hundreds of thousands of nodes in it. Mix in Whidbey and Yukon, you get over a million. Mix in Indigo, Avalon, etc., you get even more. With that much info, is a single tree the right way to go? Even if it is, can we build a control that will do it efficiently without consuming oodles of memory in your browser? Personally, I like the new tree because it's lighter weight and feels more Web-like to me, but that's just me. Feel free to post feedback to MSDN on this point using the Product Feedback Center (pick MSDN Online as the product), we're very interested in what you think.
Posted
Sep 23 2004, 08:54 AM
by
tim-ewald