On Sun, Feb 24, 2013 at 07:33:56PM +0100, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 wrote:
> This is a follow-up to
> <http://blogs.perl.org/users/ross_attrill/2013/02/dbixdatamodel---elegant-database-interaction-with-perl.html#comment-367206>.
> 
> Peter Rabbitson ✍:
> > Steven Haryanto ✍:
> 
> >> One of the things that keeps preventing me from using DBIC (and thus
> >> so far I use raw DBI/SQL) is the apparent complexity of it all.
> 
> > I hear this sentiment a lot, but any time I reach out to ask for a
> > clarification - I don't get anything back. It is frustrating :) I
> > would *so much* appreciate a comment, or an email, or a blogpost that
> > would point out complexities that *feel* unjustified. A criticism
> > like this would not go unnoticed - either the points made are going
> > to be explained away, or acknowledged and eventually fixed.
> 
> Sounds like a severe case of organisational blindness. The DBIC distro
> ships 87 non-documentation classes, of which the two most used ones,
> namely ::ResultSet and ::Row are have together over 10_000 words of
> documentation, and that's not counting the missing part in ::ResultSet,
> namely SQL::Abstract, which is the mini-language/API-within-an-API one
> has to master to become fluent in DBIC. For comparison, the short story
> <http://www.abelard.org/e-f-russell.php> has 25_000 words, takes a fast
> reader a good hour, and that's prose, not cumbersome documentation
> interspersed with code which requires much concentration to comprehend.
> 
> The bad news is that the complexity mentioned by sharyanto is the
> cognitive load this exhaustive documentation causes. A beginner is very
> intimidated by it because he cannot identify what is important and what
> not, and it's easier to give up and look for something else, or fall
> back on the familiar DBI API, than to push through the manual. It
> doesn't help that the synopsis of DBIC, albeit correct, is close to
> useless for its intended purpose.

Any proposal to rewrite it that doesn't make things even worse will be
taken up immediately. In fact given the massive scope of DBIC it may be
even wiser to drop the SYNOPSIS altogether.

> The good news is that I have identified the parts of the API which are
> used most often; the API follows the law of the vital few. Expert users
> of DBIC should be able to name them without looking them up. 

Actually you are only partially correct here - I for one *can not* name
which parts of DBIC are used more often ;) 


> I presented this at Austrian Perl workshop last year, and will soon do so
> again at German Perl workshop.
>
> The ironic news is that I am going to attempt to fix the problem of too
> much documentation by writing more. I volunteer to add
> 
>     =head1 NAME
> 
>     C<DBIx::Class::Manual::Quickstart> - up and running with DBIC in 10
>     minutes or your money back
> 
> which is to be placed between ::Manual::Glossary and ::Manual::Intro
> and has a prominent incoming link in the "GETTING HELP/SUPPORT" section
> of DBIx::Class. When it's finished, this needs to be usability tested.

This is *massively awesome*. This proposal gets a big ++ from my side,
if that matters ;)


_______________________________________________
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

Reply via email to