[Catalyst-dev] RFC, docs reorg, again

[Darren Duncan]

Kieren Diment wrote:
> Please consider this idea:
> 
> Ditch the Catalyst::Manual dist, move everhthing that's not the tutorial 
> back into Catalyst::Devel, and make a separate 
> Catalyst::Manual::Tutorial dist.
> 
> Votes please.

My own take on this is that once documentation for a project becomes 
massive, it is best to move most of it into a separate distribution.  So 
just minimal introduction and API documentation should be with the code, 
and full blown manuals and tutorials should be separate.

So my own vote is for whatever situation keeps just some basic API and info 
references with the code and keeps manuals and tutorials separate from code.

Furthermore, I vote that there should not be any duplicate package names; 
each distribution should have distinct package names only.

Furthermore, I also agree with keeping the developer-only code separate 
from the code also needed for deployment

I also practice this with my Muldis database projects.  I have at least 3 
separate distributions, the first being the Muldis D language spec (all 
documentation), the second being the Muldis Rosetta reference 
implementation of that spec (mostly code plus some API docs), the third 
being for a manual or tutorial or what have you (all documentation).  Each 
of these has a root file named Muldis::D and Muldis::Rosetta and all the 
other files are beneath those namespaces.  All the documentation is POD and 
is installable like any code.

Note that, while every one of my POD-only files has a VERSION block near 
the top with NAME, as per Perl Best Practices, I discovered that the CPAN 
indexer doesn't currently get version info from those, and so my root file 
in those cases is actually a .pm file that contains nothing but a 
corresponding Perl package declaration with $VERSION, and nothing else, so 
that the indexer does the right thing when at least the distro as a whole, 
knowing when it has been updated and so forth.

-- Darren Duncan