Features attract users; Documentation required to keep them

The Perl development community is, contrary to some reports, still very active and bringing out many innovative and handy modules. To keep growing, we need to get more people using Perl who are every-day developers - by which I mean, they consume CPAN modules, rather than create them.

Unfortunately, too often I am seeing users getting turned off Perl because the CPAN modules I direct them to are too hard to figure out. In turn, this puts the users off Perl. They really want to use the new modules, since they've heard good things about them, but they're not going to go so far as to join IRC and/or read the source code to figure stuff out.

The problem is that many of the modern CPAN modules don't seem very well documented.
There are two problems:
1) API is unstable / Documentation out of date.
Often tutorials were written against older versions of modules, and if users try to run them, they now receive errors or big warnings saying the feature is deprecated. This is confusing and off-putting for a new user. Sometimes even the documentation that ships with the module is out of date too!
2) Documentation is up to date, but hard to find.
One of the biggest complaints I hear about modern CPAN modules is that in order to find the docs for something, you already have to know the answer. This is due to the tendency to use OO and mix-in inheritance, and to document features in the module where the code exists. While that makes sense to a developer, a end-user will look at the other end of the inheritance tree, where they expect the feature to be exposed.

Developers don't like writing documentation, generally. But if we want Perl to increase the number of developers using it, someone will have to do it..
It's not enough to just tell users to "buy the book".. It's a pity that it takes a commercial incentive for good documentation to get written :(