Originally Posted by Penforhire
He's right, that most API documentation is total crap. I'd extend that belief to most technical manuals and help files.
The disconnect IMO comes from the difference between literary thought and logical thought. A math or programming major will argue that math requirements are there to teach you how to think. A liberal arts major argues that humanities requirements are there to teach you how to think. Both literal schools of thought refuse to acknowledge the other's position for fear of undermining their own.
Naturally, that means your programmers aren't going to be able to write very well, and your liberal arts majors are going to have difficulty understanding what a given function does to document it.