Monday 1 September 2008

Microsoft provides examples of the worst documentation in the software industry

During the course of my work, I rather too frequently come across Microsoft documentation which consists of definitions of the form:

"BigThing" : a BigThing is a thing which is big.


Of couse a BigThing is a thing which is big!
This tells me precisely nothing.
It annoys the hell out of me so much, and Microsoft seem to me to be a company that does this more than anyone else.
I am so annoyed I am going to start to compile a list of URL's that demonstrate what I'm talking about.
Hopefully someone from Microsoft will come across my list, and then someone else at Microsoft will agree its a good idea to not insult their customers with pages upon pages of documentation that provides no real information whatsoever.

I'm not going to go round pulling out examples now... I'm just going to add to my list every time I come across one.

Here's one that just got me... you might say it was the last straw:
evictmanagedresources

Microsoft's documentation on "evictmanagedresources" says, (and I quote) "Evicts all managed resources, including Microsoft Direct3D resources and those that are driver managed." In other words, evictmanagedresources evicts all managed resources. That really helps, doesn't it, Microsoft! Ever heard of examples? Ever thought you might like to include some in your documentation. Read my lips... never ever ever make a piece of software language documentation and don't include an example of usage.

Whoever at Microsoft needs to hear that, I don't know. But someone needs to write it in red ink on their forehead.

(Happy mood, today!)

If you're suffering from having to deal with Microsoft documentation, these fellows may help... 8-) ... Microsoft Dorset

No comments: