[Catalyst] improving usability / doc

[Matt S Trout]

On Thu, Aug 16, 2007 at 05:06:10PM +0200, Adam Bartosik 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?

That would be ugly.

Can you find anywhere that page is linked to and tell us so we can make it
link to

http://search.cpan.org/perldoc?Catalyst::Manual::Tutorial

instead, since that already shows them in the right order.
 
> There is also an open ticket for - maybe - this kind of work
> http://dev.catalyst.perl.org/ticket/82

The trac ticket system is dead and turned off, please ignore it.

> 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?

Funny, several of the people who've come to Catalyst from rails said one
of the reasons they moved was because the rails doc .... sucks.

Mostly what you're complaining about is presentation though and where things
are referenced from. If you send a message to catalyst-dev@ asking for it
one of the wiki gnomes will give you access to that and you can re-arrange
the order stuff's displayed in to your heart's content.

-- 
      Matt S Trout       Need help with your Catalyst or DBIx::Class project?
   Technical Director    Want a managed development or deployment platform?
 Shadowcat Systems Ltd.  Contact mst (at) shadowcatsystems.co.uk for a quote
http://chainsawblues.vox.com/                    http://www.shadowcat.co.uk/