C. S. Lewis wrote something in the Screwtape Letters to the effect that every vice is a virtue misapplied. Doesn't that describe software development?

CPAN is valuable because of the semi-formal guidelines which have grown up around it:

a culture of sharing

a first-come, first-served namespace policy

a culture of testing and quality

good tools to produce, bundle, install, and verify distributions

optional but free bug reporting

a standard documentation format and structure

The common Perl 5 module documentation structure—a name, a synopsis with code examples, a description, and then an API listing—is good for describing a single, standalone module. You can extend it to explain the philosophy behind your code and its use, as something like Test::More does, or you can provide a very simple explanation of a very simple API, such as strict does.

Like many of the good features of Perl 5, the CPAN documentation format borrows liberally from a feature of Unix: specifically, the format of man pages.

Like many of the not-quite-perfect features of Perl 5, features borrowed heavily from Unix show their limitations. In particular, the biggest flaw of the API-heavy documentation structure is that it's only good at documenting APIs and its passable at best at describing the important relationships between components of the distribution which provide APIs.

In other words, if you want to understand DBIC and use it effectively, you must understand the relationship between result objects and resultsets as well as the separation of responsibilities between them. (DBIC deserves credit for recognizing and addressing this documentation gap by providing multiple pieces of documentation beyond API explanations, but the problem is difficult to solve.)

You can see the problem more dramatically by exploring something like HTTP::Response, which is part of a well-factored and robust distribution but which has the relevant information spread through several separate pages of documentation because the structure of the documentation reflects the inheritance structure of the code.

Again, you can't fault Gisle for factoring his code well and documenting it effectively in the dominant style of the time (and Gisle deserves much credit for helping to spread the dominant style of documentation)—but isn't it ironic, a little bit, that where objects should be well-encapsulated black boxes that their internal design decisions are so apparent in the documentation?

Some will suggest that we need better ways to explore the documentation, but I believe there's a bigger question we need to answer. When I'm flipping through all of the documentation for DBIC to figure out the best place to put validation code to ensure that my objects always get created in a known-valid state, I need something far different than a list of methods used to search for objects that already exist. I know what I want to do, but I don't know which module's documentation holds the right answer.

I don't know what the solution is.