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
… 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.
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.