[Catalyst-dev] Cookbook RFC

[Jesse Sheidlower]

On Tue, Jul 04, 2006 at 08:59:09PM +1000, Kieren Diment wrote:
> OK, so I've done a little bit of editing on cookbook, and it's a fairly
> cumbersome job because:
> 
> a.  It's one huge flat file
> 
> b.  The order is in date of publication rather than by theme.
> 
> I propose to alter the cookbook so that there are separate sections, e.g.
> Catalyst::Cookbook::View::RSS
> 
> Catalyst::Cookbook::View::TT
> 
> Catalyst::Cookbook::Deployment::FastCGI
> 
> Catalyst::Cookbook::Deployment::ModPerl
> 
> etc.
> 
> One advantage of this is that it's easier to add new stuff in a sensible
> place.  The main maintenance headache would be keeping a suitable index in
> Cookbook.pod
> 
> What do you think.  Should I jdfi, or not.  Votes please.

What, you think this is a democracy? :-)

The problem, as I see it, is that the Advent Calender stuff
doesn't belong in the Cookbook in the form in which it
appeared in the Advent Calendar. Some doesn't belong in at
all, and most should be shortened significantly. I did a bit
of this but there's a lot more to do, obviously.

I think it can be a flat file if we trim things appropriately.
Reordering would certainly be a good idea, though, with
section headers or something. But splitting the Cookbook up
into separate files would only be appropriate if it were very
much larger, book-length larger, and while I encourage this
we're not quite there yet. The Cookbook should be a Cookbook,
a group of straightforward recipes, not a discursive essay
collection.

Adding things from the Wiki would also be a good idea.

Oh, and we should do this RSN, so we can push 5.70 out the 
door.

Jesse Sheidlower