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ɪᴇᴄᴋᴏᴡ 迪拉斯 <da...@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://email@example.com _______________________________________________ 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://firstname.lastname@example.org