Some stuff that happens in the driver world is a big deal, like the WDK becoming integrated with Visual Studio. Or, SDV finally becoming so useful all you want from it is more checking. Or, UMDF and KMDF sharing the same syntax. These are all Big Events that matter to just about every driver writer on the planet. They thus get big news, and lots of people blog, write articles, Tweet, whine, praise, and make pithy comments like “what took you so long.” But, one way or the other, most people in the driver development world hear about these big changes.
What people probably don’t realize is that there are other changes that happen that are just as important to the community, but that almost nobody talks or hears about. One of these is the steady progression of the WDK documentation over the days, weeks, months, and years.
When the Docs Sucked Weren’t Any Good So Great
If you’ve been involved in Windows driver development for a while, you might remember when the entire set of driver development documentation fit into two printed volumes totaling less than 500 pages. There were many, many, basic driver development interfaces that weren’t documented at all. The ones that were documented varied tremendously in their clarity and level of detail. Heck, for quite a while, I had a standard “call and response” I used in the Windows driver development classes I taught. As I explained a certain topic or function, I would say “But that’s…” and then I’d gesture to the class. The class would then complete my phrase in unison: “NOT DOCUMENTED!” It was great fun, and it kept (almost) everyone awake during my otherwise scintillating lectures.
That was quite a while ago. But even in more recent times, it was common that features introduced in a new operating system version weren’t necessarily documented at the same time the OS including those features was released. And for ages it was standard practice that the WDK docs were released only when the WDK was released — once per OS or service pack release. Any changes, additions, or clarifications to the docs had to wait for the next release cycle. This was true even after the WDK docs were officially available online on the Microsoft site.
Now? A World of Difference
But that was then, and this is now. I came today to praise the WDK docs and the team that creates them, not bury them. I want to call attention to some very cool things that are happening right before your eyes. Things that you might not have noticed unless you were looking carefully.
For the past few years, the WDK docs have been undergoing what I can only refer to as a “continuous improvement” program. You know that link that lets you send feedback at the bottom of each doc page (see Figure 1). They actually read that feedback. They’ll file bugs based on it. How do I know this? I’ve gotten replies… and bug resolutions… and actual documentation fixes… based on comments I’ve sent using those links. Really!
But that’s not the best part. Sure, fixing reported bugs is cool. But the major change you might not notice is that instead of being mostly reactive – fixing content problems when somebody reports a problem – the doc team has now gotten to the point where they’re being very proactive. They’re looking at doc content, without anybody specifically complaining about it, and seeing how it can be improved and made easier to find.
Need an example? Here’s one: Let’s look at the documentation about a nice, simple, topic. The Checked Build of Windows. Figure 2 shows the WDK doc page as it appeared at the beginning of this year (2014).
Not that informative, is it. But the information is there. Sort of. Some of it. But, looking at this page and having just finished helping with a major update to the OSR.COM corporate web site, I can’t help but think of this page in SEO (“Search Engine Optimization”) terms. How many people who are looking for the checked build of Windows Google “Obtaining the checked build of Windows”? Hey… the term “Windows” isn’t even on the page. Good luck finding this if you’re doing a web search.
And now we turn to Figure 3, the analogous page from the WDK as of 1 May 2014. Not only is the content useful and up to date, there’s actually a chance someone can find this page with a search. In fact, when I Google “How do I get a checked build of Windows” this page turns up in the first three results. The other two are other pages in this same group of topics.
It seems that the WDK documentation is now being updated regularly. I don’t know exactly how frequently it’s updated, but it seems to me to be pretty frequently. And this leads to an interesting issue: For many of us, after installing Visual Studio and the WDK, one of the next things we do is download the offline WDK docs. You know, in case we want to write code when you’re offline (like when you’re on a United Airlines flight from Boston to San Francisco, where the plane was made in like 1950, with little TV sets that drop down from the ceiling every 10 rows for you to watch the movie, and no room to move, and there’s no in-flight WiFi, and… oh, wait. Never mind). While the offline docs are still useful, the advantage to using the online docs is that you get the “latest and greatest” version of the docs when you access them. And now that the docs are updated frequently, that can be a significant advantage.
More Goodness
There’s more to notice and to like about how the WDK docs have progressed over the last few years. Information on features published contemporaneously with the OS that introduces those features (did you see that nice clear documentation about SPBs appeared in the RTM Windows 8 doc set?), more “how to” and “step by step” guidance for new driver writers, and more architecture, context, clarity, and usefulness in the docs for everyone, old hands included.
Here’s a good example of changes in this last category: Clarity and usefulness. The description in the WDK of the IRP’s Tail.Overlay.Thread field from not that long ago. Read it, and tell me if you understand what it means:
Tail.Overlay.Thread
Is a pointer to the caller’s thread control block. Higher-level drivers that allocate IRPs for lower-level removable-media drivers must set this field in the IRPs they allocate. Otherwise, the FSD cannot determine which thread to notify if the underlying device driver indicates that the media requires verification.
Got that? No!? Wonder WTF it’s talking about? Yeah, me too. It’s so narrow it’s just barely correct. Seriously. That was the description of this field. Do you wonder why we got questions about this field on NTDEV all the time? Compare that to the definition I just got online while I was writing this article (May 2014):
Tail.Overlay.Thread
A pointer to the caller’s thread control block (TCB). For requests that originate in user-mode, the I/O manager always sets this field to point to the TCB of the thread that issued the request.
Well, that’s a metric duckload better, don’t you think? Heck, that definition is actually useful. And accurate. This is just one example of the kind of cleanup and clarification that’s taking place throughout the WDK.
I won’t even mention how great it is to have a member of the doc team who regularly reads and contributes to the NTDEV forum (yay for Diane Olsen!). She’s quick to jump into discussions, take bug reports, and even keep us informed of major doc additions and changes.
The Best Yet
I’m not saying the WDK docs are perfect. There’s still room for improvement, of course. For example, the docs could give us more information on the error codes returned from functions and what conditions cause those errors, for example. The function call examples that appear on the doc pages could be (cough, cough) a bit less trivial than they sometimes are today. And, I will always want more architecture information… more details about design motivations, tradeoffs, and side-effects.
But if you stop for a moment and take an overall look at the latest WDK documentation, I think you’ll be both surprised and pleased at what you see. The changes really are impressive. I have no trouble saying the WDK docs are in the best state they’ve ever been in at any time in the history of Windows.
Community Interaction
What do you think about the state of the WDK docs? Tweet us @osrdrivers and use #TheNTInsider to provide your comments. Don’t tweet? C’mon…even Peter tweets. Well, there’s always Facebook and LinkedIn…or the telegraph…
OSR Open Systems Resources, Inc.