[Catalyst-dev] Documentation

[Jesse Sheidlower]

On Fri, May 12, 2006 at 01:28:16PM -0400, Jesse Sheidlower wrote:
> 
> I'm heading out now but I'll send some comments to the list (I
> know this is going to the list to) about what I'd like to see
> happen to the docs in the near future, and what work we're
> doing right now esp. on the Tutorial. 

My general thoughts include the following:

* The Tutorial should present a single application and focus on
a single way of handling any part of it--one ORM, one Template
module, etc. Alternatives can be mentioned but should not be
the focus, it can link to other docs as necessary. It should be
split into several parts, each self-contained, so that any part
of it can be followed without, or with only little, consultation
with the rest.

I've been working with hkclark on this, modifying the version of
the Tutorial he recently posted; we hope to have something to
commit to trunk^H^H^H^H^Hbranch in a week or so.

* There should be a Catalyst::Manual::Installation. This
really needs to be part of the core docs. Kennedy has a stub
version of this that others will need to modify and add to
once it's up.

* Catalyst::Manual::Internals needs to be updated and expanded
(mst, andyg, chansen, nothingmuch....). This doesn't have to
be a comprehensive guide to hacking on the dispatcher, but it
should have a rough description of how the request cycle
works, and how to mess with it, i.e. how (and why) you would
write code that interacts with the cycle. With examples!

* C::M::Intro should be a best-practices document
that focuses on things unique to Catalyst and how to use them
in working code. I don't want it to be too Cookbooky, but rather
things that someone would want to know when coming to Cat for
the first time--more info on dispatching, relationship of 
Model/Controller, etc. Many things in the current Tutorial
should be moved here.

* C::M::Cookbook should be expanded with things from the wiki
and other places.

* C::M::FAQ should probably be deleted, or we should start
really using it in a way that's distinct from the Cookbook.

Anything else.

Jesse Sheidlower
(jester)