[Catalyst] improving usability / doc

[Antano Solar]

On 8/16/07, Adam Bartosik <adam.bartosik at hurra.com> wrote:
>
> I wonder how much better Catalyst doc would looks if the "top doc page",
> http://search.cpan.org/dist/Catalyst-Manual/ (linked from top catalyst
> page)
> had tutos in 1..9 order, not alphabetical?
>
> Is such change in naming eg:
> Catalyst::Manual::Tutorial::1_Intro
> Catalyst::Manual::Tutorial::2_CatalystBasics
> possible?
>
> There is also an open ticket for - maybe - this kind of work
> http://dev.catalyst.perl.org/ticket/82
>
> I just think how can I help in this process of improving documentation
> for my favorite framework. I am a perl programmer with strong experience
> of initiating new sites, promoting, advertising - nothing special but
> could be helpful to improve cata site.
>
> Take a look at doc pages of rails:
> http://rubyonrails.org/docs
> django:
> http://www.djangoproject.com/documentation/
> or even not so popular mvc like Pylons
> http://wiki.pylonshq.com/display/pylonsdocs/Home
>
> How many people decided to take different framework just because
> catalyst doc still.... sucks?
>
> --
>
Maybe the layout sucks but not the content.
Catalyst is just a dispatcher for the real manual one must read the pod
pafges of the appropriate packages be used.
It can't be compared with rails document where 1 specific view and 1
specific ajax library and 1 specific model class is built in.
The better deal would be to just explain that the different components have
different documentation and link to it.
And as far as what I have felt , the current catalyst documentation are very
decent fo someone who has done cgi in perl before or has used any templating
with perl.
Its has just the necessary stuff to explain the role of the controller.

But for others , especially those who come from other MVC who are
potentially ignorant about templating or what actually happens within an MVC
architecture , just like I was a few days ago , I have already started a new
documentation.

It is just but the basics in a nut shell and I am not even qualified enough
to write a catalyst documentation. but I started because , a  beginner level
documentation is missing and something is better than nothing .

I will post it , when I am done with it.

Antano Solar John
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/catalyst/attachments/20070819/0b9b7=
ce4/attachment.htm