Friday, May 14, 2010

Microsoft’s increasingly lousy documentation

Something that’s irked me throughout this GCD project is just how bad Microsoft’s documentation is in a lot of places.

On the whole, I quite like MS’s documentation. The split between the “conceptual” and the reference material, and the abundance of sample code, these are all good things. A lot of it is pretty detailed, too.

But then, you also have documentation like this. Great. It sets it to run on a persistent thread. I could have guessed that from the function name. What I would like to know is, what are the implications of this? Why is this something I care about? What makes it useful?

Documentation that merely reiterates the function name is not proper documentation.

I am finding that this style of documentation is increasingly common, especially in Microsoft’s newer APIs. The older stuff is generally much richer. Not always as good as it should be—I still find the overlapped I/O docs awful, for example—but much better. Most importantly, there’s at least an effort to explain what a function call does that goes above and beyond the name of the damn thing.

We see the same thing in quite a bit of .NET documentation, too. I was recently looking at the Visual Studio 2010 SDK documentation (used for writing add-ins), and came across the same thing: documentation that repeats the function or class name, but adds no value.

I realize that documentation isn’t sexy, and that developers don’t like writing it, but that’s not really good enough for a company like Microsoft.