Just have a look at CGI.pm

"Yes, but ..."

The v4.x series of CGI.pm has introduced some drastic changes, but they were poorly communicated (see Re: Replacing CGI.pm, Re^2: "CGI::param called in list context" confusion, "CGI::param called in list context" confusion, and probably many more threads). Take it as a bad example.

If you introduce new warnings or errors, document that fact. If you break existing code, document that fact. Don't hide such information five levels deep in the filesystem. Put it into the main documentation, and make sure it is read. "Incompatible Changes" is a great heading for such kind of information. Also list such changes in your change log.

Depending on how complex your module is, and how much documentation already exist, you may want to move parts of the documentation into another POD file. If you introduce a new API, you could move the documentation for the old API to Whatever-API-v1.pod and link to that file from the main documentation. If you build up a huge amount of incompatible changes, do the same and place the link to the Whatever-incompat.pod in a prominent place of the main documentation.

If your module is a frontend to several backends, like DBI, keep the backend API documentation out of the main documentation (compare with DBI::DBD). Document what is needed for someone using the frontend.

A second problem of CGI.pm's documentation is its structure. It reads more like a cookbook and less like other module's documentation. Don't get me wrong, I like to have a cookbook, especially for complex modules. But it should not be the main documentation. After a while, you know the most frequently used functions by heart, and you want to look up other functions by name, not by purpose. Compare with DBI.

The cookbook part of CGI (the "HTTP COOKIES" and "SERVER PUSH" chapters and all chapters with headings matching /ing/i, perhaps except for "Calling CGI.pm routines") should really be in something like CGI::Cookbook. In the main documentation, I expect to find documentation for all public methods. I also expect to find the method names in the table of contents, i.e. in headings. Again, see DBI.

With all the cookbook parts removed, the main CGI v4.x documentation is quite thin:

• A big fat notice explaining that CGI.pm is no longer in core. That's for changes.
• Half-hearted deprecation of HTML-generating functions. That's important, because it changes the API.
• Compatibility with the ancient cgi-lib.pl. That was touched last time two decades ago, but people still seem to use that API.
• The usual stuff: name, synopsis, description, license, credits, bugs, "see also". All very short. (And it should not be longer.)

What's missing?

• A link to a changes document
• An overview of incompatible changes, like warnings when using param() in list context, or the ever-changing handling of file uploads. You have to search that information in the cookbook part.
• Method documentation, by method name. All the information that is burried in the cookbook.

Alexander