I've just been playing with the Facebook API for a toy project (submitted here: http://news.ycombinator.net/item?id=1743486), and utterly agree - the documentation is not even barely adequate.

The other irritating thing is when you eventually discover that there's a bug, the best response you see is "Hi, sorry this is a known issue" with no resolution date or even rough idea of whether it'll be fixed in the next year or not.