[Dbix-class] "the apparent complexity of it all"

[Torsten Raudssus]

Big thanks, Lars, for this contribution!

I will eat this documentations the next days and will find some test
victims for this. Let's see how this comes out!

On Sun, Mar 24, 2013 at 5:12 PM, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim at cpan.org> wrote:
> Pardon me for making a new top-level branch in this thread, I want to
> reply to several messages at once.
>
> Mike South ✍:
>> put a start on github and send us the url.
> <https://github.com/daxim/dbix-class/commits/master>
>
>> I will work with you on the usability testing
> Find a Perl programmer that knows some database basics. Have him work
> through the document I added. If he finishes it in ten minutes,
> expresses satisfaction and is able to apply the new knowledge to a
> different database, then I have achieved my goal.
>
> If you have a second programmer, set him up as a control. Give him the
> documentation as it is now, perhaps let him work through Manual::Intro.
>
> Jess Robinson ✍:
>> have you read/come across,
>> DBIx::Class::Tutorial? Or my, as yet not-quite-finished, book (on
>> github)?
> No, not at all. ribasushi pointed out DBIx::Class::Manual::SQLHackers
> in a private mail message. All of these were invisible to me.
>
>> I'd appreciate to know if those are more what you'd expect,
> Yes, especially SQLHackers! This sort of transferable knowledge is very
> important.
>
>> how we can help people find them
> Fold ::Tutorial and ::SQLHackers into one document each. Put them into
> the DBIC distribution.
>
>> I've tried a few times, happy to see other folks take on the matter.
> There's easily room for twenty people writing their own version of a
> DBIC beginner talk or tutorial. Let us make a competition out of it or
> something to get knowledgeable users motivated to extract from their
> mind onto the net their opinion of where a beginner should start.
>
> Peter Rabbitson ✍:
>> Or perhaps tell the respective authors
>> (castaway and frew) that "X is crap because".
> For ::Tutorial and ::SQLHackers, use exactly one schema from a
> database that actually exists in reality and is already filled with
> data. Best thing would to pave the cowpaths and simply standardise on
> the CD database across all DBIC documentation, so rewrite the parts
> with Mr. Bloggs's blog. Write the documentation so that it is usable in
> a *practical* fashion: a user must be able to paste the code as-is and
> observe the described effects; perhaps back this with Test::Synopsis or
> Pod::Snippets to make sure it stays so.
>
> I haven't finished reading the book attentively yet.
>
>> and this (which is a different "sales pitch" angle):
>> https://metacpan.org/module/RIBASUSHI/DBIx-Class-0.08208/lib/DBIx/Class/Manual/Features.pod
> This document needs a comparison with DBI/raw SQL a la
> Moose::Manual::Unsweetened. It should show off how much shorter and
> less error-prone DBIC API calls are. The examples should be taken from
> real life production code if possible.
>
> _______________________________________________
> List: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/dbix-class
> IRC: irc.perl.org#dbix-class
> SVN: http://dev.catalyst.perl.org/repos/bast/DBIx-Class/
> Searchable Archive: http://www.grokbase.com/group/dbix-class@lists.scsys.co.uk