In general, I've had very good experiences with the documentation of CPAN modules. It almost always starts with a synopsis that includes a common and simple use case that you can tweak as desired (there are exceptions, of course). I've had a much harder time with documentation for some other languages (including some commercial ones), which simply consists of lists of methods or subroutines, without anything to tie them together or to tell you where to start.