How Editing Works at the WDK
The quality of what you read when you install the Kit or visit MSDN is very important to us here at the WDK. Of course, good quality starts with careful work by our writers. However, the final touches are added by the editors. Our editing process includes several things that help you in ways that you may not realize. First, we examine language to make sure that it’s clear. This might mean that we break up long sentences, or provide definitions for new terms. Then we fix any problems with grammar, spelling, and punctuation. Finally, we examine the formatting to give it a consistent feel. It may seem like a small thing, but it makes the content easier to use if function names are always bold.
An editor’s best friend is a good style guide, and we have a couple. In most cases we are covered by the Microsoft Manual of Style for Technical Publications (MSTP), which is used by much of the software industry. It provides guidance on how to talk about applications, files and so on. For things that are more specific to driver programming, we use our own WDK style guide. This lays out how to talk about such driver specifics as IOCTLs. There are few places in the publishing world that cover as much of the operating system kernel as we do, and this requires a specialized set of terms and concepts. We are always looking for ways to improve our style guide, frequently in response to customer feedback. One improvement in the past year is the addition of lib information to our reference pages.
An especially important thing for readers is the searchability of our documentation. Editors maintain our index, which is helpful for structured searches of the compiled help offline. We also make our pages as easy to find online as possible. To do this we optimize topics for search engines, with editorial standards that include suitable placement of key search words on each page.
Another priority is to make content easy to understand for our international audience. Editors work toward this goal by making sentence structures as simple as we can, and by avoiding ambiguous words and complex verb forms. A simplified vocabulary is enforced by a tool developed at Microsoft for our writing teams.
When you attend conferences and plugfests, the people that you interact with are most likely to be developers. But be aware that when you give us feedback on the documentation, your thoughts are likely to reach an editor. We are eager to hear from you, whether it’s about a feature of the documentation such as the index, or about a gap in the description of your favorite function. Please send us any suggestions for improvements—you can be sure that we’ll listen, and unless you want to be anonymous you’ll even hear back from us.
— John Osborne, [MSFT], Editor, WDK
