by If you use the WDK doc set all day, every day, you almost certainly have a few pet peeves — things in the docs that drive you nuts and that you’d like to change. Now, you make those changes yourself! Well, almost.
In its latest move to open source, Microsoft has started putting all the WDK documentation on GitHub. No, I’m not joking. A big chunk of the the docs, in Markdown format, are already available to the community to review, file issues on, and even to submit their own changes for approval.
Initially I was skeptical about this idea. I wondered (somewhat loudly and in MSFT company) if this was merely the latest plan to reduce the cost of maintaining the complex and ever-growing suite of WDK documentation. And while cost-savings is almost certainly a major driver, after talking with a colleague on the WDK team I’ve been assured that the plan is not to open-up the docs to random edits wiki style.
In fact, the plan for handling doc changes follows the typical open source project structure. There are two ways that community members can request changes to the WDK documentation:
- Users can edit the docs themselves, and submit their proposed changes to the WDK doc team for review. This involves creating a branch for your changes, and then submitting a “pull request” (otherwise known as a PR). What’s cool about GitHub is that you can create the branch and submit the PR directly online — You don’t have to clone or download anything.
- Users can submit issues on the docs — This is more like filing a traditional bug report, with a description of a problem you’ve encountered in the docs for action by the WDK doc team.
In both cases, you can directly track your request and those of other community members.
My buddy on the doc team tells me that their current plan is to review and process PRs once a day (subject to change, of course). What’s super cool is that when a PR is accepted, the changes are merged and the updated docs are immediately published on MSDN.
I tried the system for myself yesterday. I created and submitted a PR for what amounts to little more than an editorial correction to the docs on evaluating ACPI methods. Before the end of the day Redmond time my PR had been reviewed and merged, and my change appeared in the official MSDN docs. This was not a pre-arranged trial with the WDK doc team, but I admit that the PR reviewer almost certainly recognized my username and could have given my PR special treatment.
I also filed a small doc issue which is apparently still under consideration (the issue hasn’t been assigned and there have been no comments in response to my issue… so I’m still left to wonder its status).
To be able to submit issues or make changes, you need to have a (free) account on GitHub. If your changes are anything other than trivial, you’ll also need to sign Microsoft’s Contribution License Agreement that basically says your submission belongs to you (or you and your employer), you’re authorized to submit it, and you give MSFT the right to use it.
It’s easy to make a quick change or file an issue if you find a WDK doc page on MSDN that you want to change. There’s a convenient little “Contribute” link in the upper right corner of the page. When you click it, you’re taken directly to the doc page in GitHub.
I understand that another benefit of this system is that internal MSFT folks (like devs and PMs) can use it to update, fix, and enhance documentation quickly and easily. If that leads to faster turns in the documentation — getting info and updates to the community more quickly — then that by itself will be a very good thing for the community.
The process of moving the entire WDK documentation set to GitHub (all 50K or so topics of it!) is still in progress. But you can use GitHub to file bugs on any topics that appear in the docs (whether they’re currently in GitHub or not). And, of course, you can try your hand at “fixing” the topics that are currently there.
Check the WDK Documentation on GitHub at http://github.com/Microsoft/windows-driver-docs. Find a bug. Fix it. C’mon… give it a try.
OSR Open Systems Resources, Inc.