[Dbix-class] "the apparent complexity of it all"
castaway at desert-island.me.uk
Tue Feb 26 23:22:25 GMT 2013
On Sun, 24 Feb 2013 18:33:56 -0000, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim at cpan.org>
> This is a follow-up to
> 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.
There are indeed, a lot of docs. Unfortunately most of it is reference
docs, thus describes exhaustively, what each class can do.. You're right,
the few non-reference docs we have don't seem to get found by users (or at
least I seldom hear them mentioned, when complaints about docs are
brought). The ::Manual side of things could do with tidying up.
Just out of interest, have you read/come across, DBIx::Class::Tutorial? Or
my, as yet not-quite-finished, book (on github)? I'd appreciate to know if
those are more what you'd expect, and if so, how we can help people find
> 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.
> 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. I
> presented this at Austrian Perl workshop last year, and will soon do so
> again at German Perl workshop.
I've tried a few times, happy to see other folks take on the matter.
> 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.
.. And possibly in place of the SYNOPSIS as well? Needs to be loud and
More information about the DBIx-Class