in reply to The problem of documenting complex modules.
I run into this all the time and agree with you on most counts. XML::Compile is one I had a problem getting into. There were tons of docs but nothing that walked through how to do it from start to finish. This was back in 2011 and (with help from the author of the module) I was finally able to get things working, and I did a blog post about it: Using XML::Compile to Output XSD-Compliant XML.
Most of the time, if the documentation is too confusing I just pass and find another module. I had your exact experience with Poe and PDL and never spent sufficient time to learn them. Sometimes I feel like I might be missing out.