So it looks like I'm not the only one who's a bit annoyed about crappy API documentation.

Even Microsoft can't get it right. And I'm not surprised. How many Microsoft developers have been on a creative writing course? Something to think about Bill.

Like I said before, API documentation is hard problem. The only way to produce good API docs is to get the developers to write good copy. No two ways about it. It's a good skill to have and something that should be encouraged. And yes, I know, it's damn hard.