[Catalyst] Catalyst-Devel Patch

[Todd Rinaldo]

J, Thanks for the detailed reply. I hadn't thought about the base
class nature of this class. Catalyst and DBIC are both MAJOR
development projects. This means their documentation on CPAN gets
spread broadly over many pages. I admit this is not a problem for most
modules on CPAN. I suppose my patch was specifically aimed at dealing
with some of this. I have countless times asked questions on a
list/IRC which was clearly documented on a page I'd reviewed multiple
times. Once I knew where to look, the answer was easy.

I am a major fan of wiki, as it's low entry barrier can make it easy
for the people who most need the information (newbies) to append to
the docs or clarify the docs once they get their answer. I'll take a
look at the available wikis. When I'm done, I suspect my comment will
be, well if this is the best place to put the docs on useability,
shouldn't we point to it from the POD? This would effectivley allow us
to separate the design specs related stuff (POD) from the practical
use (WIKI). What are your thoughts on this approach?

Todd

On Sun, Jul 20, 2008 at 10:38 PM, J. Shirley <jshirley at gmail.com> wrote:
> On Sun, Jul 20, 2008 at 7:49 PM, Todd Rinaldo <toddr at null.net> wrote:
>> Hi,
>>
>> I still think something should go in the manual explaining how this
>> works. I spent quite a bit of time trying to figure out how
>> Catalyst::Helper did it's magic. If a code reference shouldn't go in,
>> then could I recommend a link to the FAQ. I think allot of people get
>> their start with DBIC using Catalyst::Helper and so it's the natural
>> place they would look first.
>>
>> [snip]
>
> The main point is that Catalyst::Helper is specific to Catalyst, and
> has absolutely zero relevance to DBIx::Class.
>
> If you want something in the Catalyst::Helper space, something
> specific to DBIC would be the right place.
>
> As an example, Catalyst::Model::DBIC::Schema:
> http://search.cpan.org/~blblack/Catalyst-Model-DBIC-Schema-0.20/lib/Catalyst/Model/DBIC/Schema.pm
>
> But, again, the question you are asking is already answered in the
> Catalyst::Helper::Model::DBIC::Schema documents:
> http://search.cpan.org/~blblack/Catalyst-Model-DBIC-Schema-0.20/lib/Catalyst/Helper/Model/DBIC/Schema.pm
>
> The relevant excerpt:
> create=static instructs this Helper to generate the named Schema class
> for you, using DBIx::Class::Schema::Loader in "one shot" mode to
> create a standard, manually-defined DBIx::Class::Schema setup, based
> on what the Loader sees in your database at this moment. A
> Schema/Model pair generated this way will not require
> DBIx::Class::Schema::Loader at runtime, and will not automatically
> adapt itself to changes in your database structure. You can edit the
> generated classes by hand to refine them.
>
> So, what we have is documentation to use
> Catalyst::Helper::Model::DBIC::Schema or to use DBIx::Class directly
> and the make_schema_at method.
>
> If you'll note, Catalyst::Helper's pod, almost in entirety, is focused
> on people writing generic model, view and controller classes - and not
> for end users.  In fact, even in Catalyst::Manual::Cookbook the only
> reference to DBIC is a link to Catalyst::Model::DBIC::Schema.  Further
> reading of that page, in the description section, it hints at your
> question:
> "This is a Catalyst Model for DBIx::Class::Schema-based Models. See
> the documentation for Catalyst::Helper::Model::DBIC::Schema for
> information on generating these Models via Helper scripts."
>
> The link there finally answers the specifics of the question on how to
> generate DBIC classes from an existing database, and in very specific
> detail.
>
> It's unreasonable to expect Catalyst core documentation to reference
> any specific model that may or may not be used.  Simply because
> Catalyst and DBIC are most commonly used together does not mean that
> the Catalyst community endorses DBIC as the only ORM.  If you ask our
> advice, we will recommend it (more in the way of, if you don't know
> why you should use it over others, you should use it).
>
> Now, please note I'm not saying that search.cpan.org or Pod in its
> current form is the best solution for documentation.  I think it could
> use work, and that would help increase findability.  As always,
> patches welcome and all that.  I just think that your patch is a
> misguided attempt to help because you failed to read other relevant
> documentation.  I don't want to discourage you from helping just
> because I'm saying no, because there are other ways to address your
> very valid issue of not finding the right information.
>
> If you agree with me in my feelings that finding this information is
> the issue, and not the location (and increasing where the information
> is found is not a solution), perhaps the right solution is to submit
> this on the wiki, or start a blog, or if you have one use a catalyst,
> perl or dbic tag, write an article and then submit your blog to be
> included on planet.catalystframework.org.  This is always preferable
> than adding in more, and potentially irrelevant, documentation in an
> area where it doesn't belong.
>
> On the wiki, there is already a DBIC FAQ that would be the perfect location:
> http://dev.catalystframework.org/dbicfaq
>
> Thanks and I hope to see your contributions on the wiki,
> -J
>
> _______________________________________________
> List: Catalyst at lists.scsys.co.uk
> Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
> Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/
> Dev site: http://dev.catalyst.perl.org/
>
>