For a long time, the WDK documentation grew, adding new sections and documentation for new functions.  Until recently, in spite of this growth or perhaps because of it, the documentation didn't necessarily improve.  However, for the past year or two we've started to notice improvements in the WDK docs.  This caused us to wonder: What's changed?  More resources?  Different people?  Could it be that the documentation team is more focused on listening to the community?

To try to get to the bottom of these changes, and follow-up on several long-standing community requests, we sat down with WDK Documentation Manager Dagmar Shannon.  If there's something different going on with the WDK docs, she's certainly the one who can tell us what's up.

NT INSIDER: I know you're the "WDK Documentation Manager" -- What does that really mean?  What in the WDK are you responsible for?

DAGMAR: Well as you may well know I am counted in our financial spreadsheets as "Management overhead" and as such I don't produce very much! We have a great team of about 19 programming writers and 3 editors and we are all passionate about the over 20 technologies that we support. However, my duty is to see that we are a well-functioning team and that I make sure we reach our goals of providing documentation that our customers need to be able to build robust drivers: in other words, to provide documentation that is complete and accurate. We don't always reach that goal but we have been getting better.

You know our doc set includes documentation that is 10 to 15 years old in some places, and we can't always go back and clean up everything as we would like because we also have the duty to provide the reference pages and design guides for each new operating system that comes out. Having this dual pull of updating the old and providing the new that is a real challenge for us. For the Server 2008 release you may have noticed that we finally did a scrub of the old Kernel reference topics.  These were reworked by the doc team for completeness and reviewed by our Kernel developers for accuracy.

My particular passion is in the area of customer connection and listening to them. Since I started we have added the Wiki to our topics on MSDN, started to publish updates monthly on MSDN instead of quarterly, we have added the Debugger, Performance Analyzer Tool Kit (under Diagnostics) and WLK docs to MSDN, have the updated WDK docs available as downloads from WHDC monthly (http://www.microsoft.com/whdc/DevTools/WDK/WDKdocs.mspx) and we have had over 50,000 of this not so small download since we started last August. Not bad numbers. I think we really filled a need when we started that. Additionally we have made other improvements to the Server 2008/SP1 docs that I hope meet with the approval of our customers. These include completing the Index, adding subset filtering for search, and creating the Requirement Block in all new topics. Many of these improvements were based on customer feedback.

Anyway, I love my job and the team and our customers. Keep that feedback coming, I'm listening...

NT INSIDER: You mentioned that you're passionate about customer connections... Who do you envision your customers and target audience to be?  Or, are there many target audiences?

DAGMAR: We have basically 2 different target audiences. Our surveys tell us (yes, we listen, so please continue to fill them out) that about 50% of our customers are driver developers with 5 years or less experience. For them we need to make our documentation more task-based, define a roadmap and create entry points to our documentation so they know how to get started. The other 50% has 5 plus years of experience and we need to continue to provide them with architectural and conceptual overviews, point them to the great new improvements Microsoft made with the new driver models (particularly WDF), as well as acquaint them with the new tools we are providing for testing their drivers.

NT INSIDER: It seems to me that there are multiple ways to document "driver writing."  One way is that you can document key aspects of the O/S and I/O Subsystem architecture, and from that describe how drivers fit into the world.  Another is to provide a more "task based" approach: Give a series of steps for writing a particular type of driver.   Do the WDK docs adopt either of these approaches, or do they try to do something different?

DAGMAR:  It is important for driver developers to have both the architectural knowledge of how their driver fits into the OS and a task-based understanding of the steps needed to get a driver to work.  We strive to provide both types of information. Getting the balance right can be a challenge. I think that, in the past, we have neglected the task-based information that should help to guide driver writers through the development of a driver from start to finish. I'm encouraging our writers to provide a more task-based emphasis. But we also understand that our audience needs to understand how their driver fits into Windows, and how it interacts with other drivers and system components.

NT INSIDER: It's a hot topic in the community, and I've had so little fun with it I have to ask:  Why in the world did you guys change over from using HTML Help, which most of us in the community disliked but at least were used to... to Microsoft Document Explorer, which most of us in the community appear to loathe? 

DAGMAR: Well, Doc Explorer. You know that in Vista originally Help 2.0 (.chm format) was not going to be supported so we had to switch to the new .hsx format and its reader was Doc Explorer! But, we read the forums and we know that our customers are not fond of it to put it mildly, although every now and then some folks say it's not so bad. In response we have created the Subset Filtering feature in the Server 2008 docs. It allows the user to search only the technology area they are interested in and that should make search faster. If you haven't tried it you should; you may be pleasantly surprised! We also have full text search and you can type in any string and the full text search will find all occurrences, including the one you are looking for.

We have given much feedback to the group that owns Doc Explorer from the comments we found in the forums and have asked for changes and feature improvements, and I am happy to say that things are happening. We may be seeing the end of Doc Explorer in the not so distant future. Check out the video on Channel 9 for what's up with that. (See http://channel9.msdn.com/Showpost.aspx?postid=377501)

NT INSIDER: Speaking of Doc Explorer:  Several community members have commented that there's the ability to search community web sites (so called "Codezone community") for possible answers... but the sites are almost entirely .NET and C# related (my favorite is 4GuysFromRolla.com).  Why aren't there any sites relevant to the driver community (such as OSR Online, perhaps)?

DAGMAR: I believe that Doc Explorer was originally developed by the Visual Studio team and they optimized for VS and therefore you have the ability to search the Codezone community for what they were interested in, and not for the Driver community. Since there is no more active work being done on Doc Explorer there is no way we can still drive changes to it.

NT INSIDER: OK... so much for the whole Doc Explorer issue then.  I bet a lot of folks will be pleased to know it may be going away.

To a different question area entirely:  Members of the community sometimes ask "The WDK docs say we should do xyz, but community experts say I should do something different.  Is it OK for me do to something that's not specifically recommended in the WDK?"  I usually tell them it's OK, as long as there's nothing in the WDK that says not to do it, you know?  So, anyhow, my question is:  Do you intend the WDK Docs to be the definitive word on Windows driver design, explaining all the possible engineering options and trade-offs for each situation, or do you intend the WDK Docs to be more of a general guide to best practices for typical requirements? 

DAGMAR: I wish I could say the former, but it has to be the latter. We try to provide the best documentation for all users and to be able to think about and document all possible engineering option in the real world and each situation would go way beyond in scope of what we can realistically do.

NT INSIDER:  Right.  Good.  Of course, the Reference Manuals are another issue entirely.  Do you intend these to be the definitive reference on the functions they document?

DAGMAR: Yes, here we are more specific and we do document every function that appears in the header files we publish in the WDK. Or at least we try to. If you come across a function in the header files that's not documented, please let us know!  When we hear from our customers that items are missing or incorrect we try our utmost to get these fixed as quickly as possible and updated on MSDN.

NT INSIDER: For a long time, the driver development community has requested certain information be added to the Kernel Driver Reference Manual.  This information includes the O/S in which the function was first introduced, and a definitive list of error codes (or exception codes) that a function can return.  Has there been any progress in adding this material?

DAGMAR: Yes, we have made progress with supplying the OS version in which a function was first introduced. We have started to address the OS version in the new Requirements Block addition for all new reference pages for Windows Server 2008. For Windows 7 you will see an expanded Requirements Block and hopefully one that covers all ref page topics, including the Kernel. However, here we will not become "historical", in the sense that we will not say "made available in NT 3.1" but only go back as far as the OS that is still supported by Microsoft.

Regarding the definite list of error codes a function can return we doc most of the error codes for the most common situations, but we have no way of simulating every possible situation and documenting all the error codes that may come up. Again the scope here would be way beyond our capacity.

NT INSIDER: The community has long asked for code snippets to be included in the documentation like they are in the SDK.  Any progress on this?

DAGMAR:   We've already added some, you know, in the KMDF documentation.  And we've talked about adding more code snippets in future versions. I can't promise that we can make big improvements here for Windows 7 but will definitely make that a goal for Windows 8 or whatever it will be called officially. We hear you, and we are looking to include more snippets in the future.

NT INSIDER: Are you doing anything to get info into the Docs faster?  For example, when Windows XP was released it included some new functions and features, but the DDK Docs for those functions and features didn't appear in the RTM Windows XP DDK.   In fact, we had to wait for the next DDK/WDK release to get this information.  This lag, between OS being able and driver docs about the new O/S features being available, has in the past caused the community significant pain.

DAGMAR: Yes, we definitely are. I mentioned to you earlier that we always toggle between catching up with work items on already released versions of the OS, such as you mention here for XP, and working on the new functions for the to be released OS. For Win7 our highest priority will be to release the complete set of new functions in the ref topics as well as a description on how to use them in the design guide. Working on backlog items, while still important, will take second seat. We need to deliver, moving forward, completely on each new OS version.  And don't forget, as I said earlier, you don't have to wait for the next release to get updated WDK docs anymore.  We release updates on a monthly basis via the WHDC web site. (See http://www.microsoft.com/whdc/DevTools/WDK/WDKdocs.mspx)

NT INSIDER: One problem that I know I have when I download a new set of WDK docs, either as part of a newly released WDK or as a separate doc update, is that it's not clear to me what's changed from the last release (or two).  Have you given any thought to providing "change bars" or some other indication as to what's been updated in a given release (or since a given previous release)?

DAGMAR: Yes, we are discussing this in the team. I have brought that up more than once, but the devil is in the details. If we put a "new" icon on anything that has changed in the Table of Contents, for how long should we keep it there? When will it cease to be new? The best we have come up with is dating our topics (in addition to the built date that is currently shown) and you should be able to search by that date to find out when a topic has been added, been reworked or had fixes made to it. Would you and your readers think that that is a good idea?

This is especially important for MSDN (and WHDC downloads) because each month the updated doc set has roughly 50 to 60 fixes or changes (many of them customer reported). How will anyone know what has changed?

For the regular milestone releases of the docs, a great way to find out what's new is by reading the "New Information" section of the docs, but our survey results and our tracking on MSDN show us that few people do. You should always check out the "New Information" section.

NT INSIDER: Hmmmm... I think either dating the sections, or perhaps having some information that can be selectively displayed, such as dynamically putting change bars on content added after a selected major release (XP or later, S03 and later, Vista and later, etc) would be a good idea... if that's even possible in Doc Explorer.

What can you tell me about addressing the needs of our community members who do not natively speak English?  What accommodations are made for them?  I know you've started to do "automated translation" of some (or all?) of the WDK documentation, and several community members with whom I've discussed this have told me the results are pretty bad.   Is that what you're hearing too?

DAGMAR: You are referring to the MSDN pilot raw machine translation program that unfortunately ended Feb 28th 2008. Yes, as with all raw machine translations the result is not always optimal, but this new side-by-side format is really great. The user has the machine translation and the English version side by side with the same paragraph highlighted in each language. At least the user will always know where they are with regard to the English and if the translated text is not usable they can always fall back to the original English. That way they are no worse off than before when they had English only.

The feedback on the pilot showed that 56% of the people who answered the survey said that the side-by-side machine translation was better than English only (only 29% preferred English only). And the WDK was the 5th most viewed doc set out of 10. Given that some of the top 5 were just homepages in different languages I assume that we are among the top 3 doc sets viewed. I think that showed that there is real interest here and we are pursuing offering some form of machine translation in the side-by-side format later on this year. We are working with MSDN who is sponsoring this feature. In the meantime you can check out http://translator.live.com. It will translate any webpage in the side-by-side format dynamically, including our docs, topic by topic.   

NT INSIDER: Aside from the WDK Docs, what other methods are you using to get information to the driver development community?

DAGMAR: I'm glad you asked that. Just a couple months or so we started a new blog, where we do topics ranging from tips and tricks for Doc Explorer, to instruction on the use of the new doc features that are in the Server2008 docs, to writers sharing their favorite technology news with you. Additionally we will mention what types of changes we have made in each update of the MSDN and WHDC docs. Currently our blog post asks a question on a proposed addition of a Roadmap topic for the Win 7 docs and if you all think that this would be worthwhile for you to have. Check it out and give us feedback! (See http://blogs.msdn.com/wdkdocs/)

Additionally we post small articles on WHDC and sometimes work with you and the MVPs to try and get the word out. Do you have any other suggestions for us as to where our customers would like us to post?

NT INSIDER: While I have you here, I've got to ask: What does the "Send feedback on this topic" do?  You guys don't really read the email you get from this link, do you?  I mean... Even when I've clicked it and sent email, I don't think I've ever gotten back a real answer saying "OK, that's a bug, and it's fixed in version blah blah."  So, what gives?

DAGMAR: Well, we actually do send back an e-mail message to say, if you reported a bug, it will be fixed. We cannot always be so specific as to exactly when. But to show you that we do fix these customer reported bugs I challenge you and all your readers to check in the next update on MSDN (or WHDC) to see if your feedback, if actionable, got fixed. About 50% of feedback gets fixed within a month. The other half may take a little longer if it points out a problem that is not in our control, where we have a dependency on another team. But overall I would say that 90% of the feedback gets fixed within 3 months. If you find this not to be so, let me know!

Additionally we have other ways to get feedback from our customers. We track usage, such as page views and rating from MSDN. So please use the system to rate our topics. If you like what you see and find what you need, give us a good rating and a comment. Of course if you don't, tell us that too and rate the topic accordingly. We do look at that stuff. And, as I mentioned before, we do surveys and of course we have the feedback link on each page of our doc set. So we get quite a bit of feedback, but some feedback isn't actionable. If you say "great content" we won't know why it was great and we can't repeat what made it great.  If you say "this sucks" we don't know what it is and we can't correct it nor avoid it again in the next version. So if you give us feedback, please make it actionable. We love to hear from you and we listen, even if we cannot always respond as quickly as you and we'd like.

NT INSIDER: Dagmar, thanks very much for being so generous with your time.  I hope community members can look forward to seeing you at WinHEC this year.

DAGMAR: Thank you for giving me this opportunity to speak with you and through you to a wider audience. I have enjoyed it.  And yes, I hope to be at WinHec this year and to see you all there.