Creating SDKs: Posting online
If you're not aware yet, the WinFX SDK is now available as a download in either an exe form or ISO form. Also, the docs are browsable online on our MSDN site. Finally, later this week, the Visual Studio 2005 Extensions for WinFX Beta 1 (formerly codenamed "Fidalgo") will also be available for download. Aside from the standard caveat that these are Beta docs, please play with them and do not hesitate to send us your feedback on them, whether through blog comments, newsgroup postings, the feedback links at the bottom of each page in the SDKs online, or in person at PDC05 in Los Angeles next month. A number of us will be at PDC from the SDK team and we'll be actively soliciting your feedback about our SDKs. Everything from complaints about page behaviors to your specific visions for our SDKs is welcomed, no matter how you contact us.
I was one of the PMs in charge of posting the SDK docs online this time, as I used to be in my previous job at MSDN. I thought you might be interested in learning a little bit about the process of getting docs posted from the offline libraries to online, and why they often look so different from how the look offline.
In a previous post I wrote about all the various components of an HxS: the HxC, HxKs, HxT, etc. It's an alphabet soup of different XML files that all work together to create an HxS that's compliant with the various requirements of the Dexplore browser and the teams that we drop to. Dexplore is the name of the frame in which offline docs are viewed. All of this is a very complex and unique process, which makes it tough for a developer to get up to speed. However, once a dev is up to speed, things are relatively smooth sailing in the offline product. Each HxS is essentially independent from its peers when it appears in a combined offline collection, and therefore custom behaviors can be easily managed in each individual project. Therefore, a dev can pretty much create whatever they'd like, test it in a seperate and discrete environment, and then drop it to the CD.
Online is completely different, though. In an online library, CSS and Js files have to co-exist with the site's CSS and Js files. Sometimes the interaction will causes fonts to appear too small or cause Js behaviors to not work as expected. For instance, in the online structure, a page is essentially one large table, whether or not the page was intended to be a table. Therefore, we can sometimes see bizarre behavior from nested tables or broken DIV tags. In the online structure, common tags like HEAD and BODY are only applied on the client side; on the server side, docs don't contain those tags. That can also often cause problems with custom onpageload styles, and that's yet another thing to work around.
The biggest part of building docs for online is trying to get them to look and feel like their offline counterparts. We often have to do some major surgery to get behaviors to work as necessary, and remove certain functionality. For instance, the Whidbey docs offline have a non-scrolling region for the title section of the docs. That area of the page stays in the same place all the time, and everything below it scrolls. Online, that's a problem. For one thing, the amount of space availabale for the text region in the MSDN frameset dictates that we have as much available space as possible for the docs. For another, that functionality also munges the up/down and left/right scrolling in such a way that a page is very difficult to read and navigate. Therefore, we have to remove that functionality each time a page is built to the site.
Another example is the drop-down language filter functionality for the WinFX docs. You may notice when looking at the docs that many pages now have "XAML" available in the drop-down filter. (We're working to provide sample code for "XAML", by the way, so stand by for that in future releases) Adding the functionality to allow for "XAML" as a new language was more complicated than we had hoped - there are so many odd depenedencies in the Js files that getting that filter to work was a major task.
Because this process is decentralized, many different teams use different tools from each other to create docs. In doing so, they use different methods of creating the same functionality. One team's expand/contract functionality may be completely different from another team's functionalty, and this ends up being a fun chore for the build teams. And sometimes there's just no fixing particular problems. That's why sometimes drop-down language filters don't work correctly or language filters overlay sample tags. Bottom line is we do as best we can. Please let us know if you see any major problems with our site, and we'll do our best to fix them.