Hi Everyone, I'm Ken Milne, the Documentation PM for the Windows SDK. My work touches all aspects of aggregating documentation content and documentation-related features into the Windows SDK.

 

As we rapidly approach the date when the Windows SDK will ship for Windows Vista Beta 2, we are closing down on numerous issues in the docs and striving to improve the overall documentation quality in many areas. There are ton of issues in documentation that drive me nuts, but the one that’s driving me crazy today is broken links. There are few things more annoying than knowing I’m hot on the trail of exactly the right piece of information I need to do my job when I get 

 

Sorry, no topics were found for the selected link.

Keywords = "3fc0e979-dad6-4f28-81ec-8707c0f0efdc"

IndexMoniker =

SourceURL =

 

… and I’m stopped dead in my tracks. Blecchh! I’m frustrated, I feel like I’ve wasted time, and my search for that elusive piece of information I need in order to move forward takes me back to where I began. It’s not only a colossal drag, it’s the kind of thing that I want to see us completely eliminate from the Windows SDK by the time we ship the RTM version of the Windows Vista OS.

 

The good news is, we’re making progress. There are still far too many broken links in the Windows SDK, but we are well on our way to driving that number down. Here are some facts:

 

  • The Windows SDK documentation includes 2.37 million hyperlinks. As Microsoft continues to document new WinFX features and the 7000 new unmanaged APIs that ship in Windows Vista, that number grows every day.

 

  • We currently have 24,000 broken links in the Windows SDK. This means that around 1% of all our links don’t work in our current builds. 

 

  • 24,000 broken links is 24,000 too many. That said, we had 37,000 broken links in the documentation a few weeks ago. Thanks to great work by our documentation build and production team, we’ve made up a lot of ground by eliminating a lot of broken links in our managed reference documentation. The User Education (UE) teams who contribute the documentation that we ship in the Windows SDK team have also done an admirable job of fixing broken links in the content that they own and deliver.

 

Since the SDK contains hundreds of thousands of Help topics, you may wonder how we find all of these broken links in the first place. We use an internally developed tool called HavMatLite to seek out these pesky links. HavMatLite checks how links in the HTML Help 2.x (a.k.a. Havana) system resolve. HavMatLite generates a broken link report for each .HxS file we ship, and then we pass those reports along to the UE team that owns the file. It’s that team’s job to investigate and fix broken links, and include those fixes in future content drops to the SDK. Progress is iterative, and we run the HavMatLite tests frequently to see how we’re doing overall. The SDK team itself owns several of these files and we make it a priority to fix broken links in all of the conceptual, samples, how to, and reference content we own and build. 

 

Is there anything that drives you crazy about the Windows SDK documentation? Let us know! It’s my hope that you find the Windows SDK documentation useful and informative, so any comments you have on how we can improve doc quality overall is greatly appreciated.

 

Ken