On Sun, 24 Feb 2013 18:33:56 -0000, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <da...@cpan.org>
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.
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
them
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
visible, apparently.
Jess
_______________________________________________
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
