While we're having a rant about documentation ...

If you're writing a module tell me exactly what it does in the simplest terms possible, sure it obvious to you what it does, but while it might solve my problem I won't know what it does unless you tell me!

There are too many modules whose documentation is typically:

Name

Purple::Blovinator

Description

Implements lib_blovinator on the purple operating system. See lib_blovinator's documentation for interface.

Firstly, I have no idea what lib_blovinator does. It may solve my problem. Secondly, while you may be able to map a C API to perl simply by reading the C docs, not everyone can - including myself.

OK, I feel better now.