I agree with your sentiment. I found datatables initially easy to set up and use, but I soon found the documentation to be sorely lacking. Searches for the most basic customizations led to SO answers outlining ugly workarounds when all I really needed to know was the name of the right flag.
The examples on the site aren't general or plentiful enough, and they assume more prior knowledge of the plugin than would seem reasonable. I couldn't even find a list of initialization options anywhere.
A full list of options are available here: http://datatables.net/ref . However, I totally accept that the documentation isn't up to scratch, which I why I'm working on completely redoing it.
I'd be interested to know of any particular pain points you had so I can ensure they are addressed.
The examples on the site aren't general or plentiful enough, and they assume more prior knowledge of the plugin than would seem reasonable. I couldn't even find a list of initialization options anywhere.