[Catalyst-dev] Re: [Catalyst] Re: Last Chance / Last Day: Web development platform contest and Perl / Catalyst

[victori at lamer0.com]

I completely agree on what you proposed. Keep the documentation on  
the catalyst site. The current documentation is bland and hard to  
navigate. The documentation should be structured in a way where it  
would be easily accessible by a beginner. It needs to flow from easy  
beginner Catalyst tasks to more advance topics. Up front I would  
suggest listing *preferred* components to use and the ones to avoid.

wiki should be used as a dumping ground for documentation. Think of  
it as svn trunk for community driven documentation. Pull it from the  
wiki back to the main catalyst documentation so it is coherent and  
structured. Concerning spam, Trac has spamfilters now, so it should  
be more manageable.

Just my two cents.


-Victor

On Dec 4, 2006, at 11:37 AM, Jonathan Rockway wrote:

> Michael Reece wrote:
>> <cut>
>> and get a big "*Not found*" from search.cpan.org
>
> Well, we don't control search.cpan.org, so that's really not something
> we can help.  www.jrock.us doesn't contain the Ruby on Rails docs,  
> so if
> you go looking for them there, you'll be out of luck.  Yes, I know I'm
> difficult :)
>
> However, I think it would be good to keep up-to-date documentation on
> the Catalyst website.  This way we can ensure that things are up to
> date.  With a bit of CSS, we can spice up the look-and-feel also.
>
> Eventually we'll want to automate this whenever a new release is  
> tagged
> (which means that new releases actually need to be tagged ;), but for
> now, a static site is fine.
>
> Also, I think it's time for a homepage redesign.  It's nice  
> looking, but
> there's zero information.  ABW thinks it's nice, OK, that's great :)
>
> Once that's done, we should start moving stuff from the wiki to a
> nice-looking static site... even I can't find anything on the wiki,  
> and
> am always surprised to hear that there's good information there.   
> It's a
> shame to hide good information, just because a wiki is easy to edit.
>
> Anyway, I'll put together a tarball of xhtml'd docs (and CSS) and post
> it to dev@ ASAP.  It will probably be core first, and then a  
> subsection
> of modules.  Here's what my mental picture looks like right now:
>
> Main doc page
> * intro to Catalyst blurb
> * Catalyst API
> * Tutorial
> * Other manual pages
> * Modules
>
> Catalyst API:
> * (the usual PODs for Catalyst::*)
>
> Tutorial:
> * easily browsable tutorial, probably on a single page (easier IMHO).
> maybe a LaTeX'd PDF download for reading on the train or whatever.
> (easy to do with pod2latex)
>
> Other man pages:
> * C::M::Deployment and similar
> * old advent calendar entires
>
> Modules:
>  * Plugins
>    * C::P::Foo -> link to POD
>    * C::P::Bar -> link to POD
>    * ...
>  * Ms
>    * C::M::DBIC::Schema -> link to POD
>  * Cs
>    * BindLex -> ...
>  * Vs
>    * TT/TTSite/etc. -> ...
>
> and so on.
>
> Finally, I think I'll add a header to each page to make them fit in  
> with
> the catalystframework.org style, and have links to the mailing list
> archives and RT on each page (so people can report issues).
>
> Comments?
>
> Regards,
> Jonathan Rockway
>
> -- 
> package JAPH;use Catalyst qw/-Debug/;($;=JAPH)->config(name => do {
> $,.=reverse qw[Jonathan tsu rehton lre rekca Rockway][$_].[split //,
> ";$;"]->[$_].q; ;for 1..4;$,=~s;^.;;;$,});$;->setup;
>
> _______________________________________________
> Catalyst-dev mailing list
> Catalyst-dev at lists.rawmode.org
> http://lists.rawmode.org/mailman/listinfo/catalyst-dev