Quantcast

"the apparent complexity of it all"

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

"the apparent complexity of it all"

Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
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.

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.

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.

_______________________________________________
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@...

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Peter Rabbitson-2
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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Mike South
In reply to this post by Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯

On Sun, Feb 24, 2013 at 12:33 PM, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <[hidden email]> 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

...
 
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.

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.

If you do this on github I will work with you on the usability testing and/or contribute to the substance.  I came in to DBIC by doing maintenance code and adding features to an existing project, and a lot of what I did was find a similar working example in the code and modify until it worked.  I can confirm that it's a pretty bewildering technology to get a handle on.  I'm starting something from the ground up using it now, and consequently learning it "for real", but I'm still new enough to it that I should be able to remember what's confusing when you hit it the first time.

Anyway--like I said, put a start on github and send us the url.

mike

_______________________________________________
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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Peter Rabbitson-2
On Sun, Feb 24, 2013 at 11:05:37PM -0600, Mike South wrote:

> If you do this on github I will work with you on the usability testing

Just on a tangent - DBIC itself has a github mirror, and pull requests
are actively acted upon. So if you can think of one-off doc-fixes, or
even rewriting larger chunks - please do not hesitate to send us a
patch.

https://metacpan.org/module/DBIx::Class#GETTING-HELP-SUPPORT

Cheers


_______________________________________________
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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Jess Robinson
In reply to this post by Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
On Sun, 24 Feb 2013 18:33:56 -0000, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <[hidden email]>  
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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
In reply to this post by Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
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@...

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "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ɪᴇᴄᴋᴏᴡ 迪拉斯 <[hidden email]> 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@...

_______________________________________________
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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Peter Rabbitson-2
In reply to this post by Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
On Sun, Mar 24, 2013 at 05:12:24PM +0100, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 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>

Thank you for that! This is a nice start, hope we get some feedback from
other folk versed in doc-writing, so we can get some acks to merge the
big stuff/

As noted earlier - I am refraining from style comments because it is not
my forte. Follow some factual corrections and then some inlined replies.

On commits as found in that github repo:

> 70d1ba4 development info is less important than user info
Merged to master as 6ed05cfdb

> 904f0f4 improve mark-up
Merged as 53aa53f (though at some point I need to clarify what "rapidly"
means there...)

> 0b1cd47 improve outline by introducing synopsis subheadings
Merged as 5b56d1a.
I wonder whether this should not mention DBIx::Class::Schema::Loader from
the start.
Also note that there is general buy-in from most of the cabal that
DBIx::Class::Candy could be mentioned as a replacement for the current
way of doing things (while the current way continues to function
indefinitely of course). There is a number of unagreed-upon-deficiencies
in ::Candy (i.e. some believe it does not make some bad designs
obvious). Yet afaik everyone more or less recognizes the value of less
typing for a beginner.
These comments are just food for future thought.

> d215766 improve outline: thematically grouped topic
I am vetoing this (and I am pretty certain mst would too if he was
looking ;). AUTHOR and CONTRIBUTORS must remain on the same level. If
you want to make them both =head2 - that is fine. The current patch
as-is implies a certain hierarchy which does not exist.

> 1f6018a POD best practices
First to be merged as 97ad6fb878, added you to contribs

>974c7e5 quick-start documentation
Not merged. Waiting for more input from the rest as mentioned earlier

>cc3ad59 point out where in the docs a user is most likely to spend reading time
Not merged. While I like the idea, I am not sure if mentioning
DBIC::Row DBIC::Rel::Base (which is about to go away soon... I hope... I
really do) is a good idea. Especially given that we have
https://metacpan.org/module/DBIx::Class::Manual::ResultClass#INHERITED-METHODS.
Also I would recommend changing L<SQL::Abstract> to
L<SQL::Abstract|SQL::Abstract/WHERE CLAUSES>. A DBIC user is unlikely to
*ever* need the other parts SQLA provides (that is the SQLA
implementations of C/U/D of CRUD)

Thank you for this start!

> > how we can help people find them
> Fold ::Tutorial and ::SQLHackers into one document each. Put them into
> the DBIC distribution.

My particular gripe with that would be putting us in a position of
making releases for docfixes only. Given how core of a depenency DBIC
is, I am wary of getting users into "update fatigue" state [1]. Perhaps
we should have a separate test-less DBIx::Class::ExtendedManual dist
which is a direct dependency of DBIx::Class? Then a lot of this stuff
could go there (under the usual DBIx::Class::Manual:: namespace, the
ExtendedManual above is just to clarify the dist purpose)

> > 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.

Afaik it is a real-life production (frew will have to clarify this)

[1] I am in fact so wary of frequent updates that I felt the need to
apologize on twitter for a flurry of sub-quality releases last month:
https://twitter.com/dbix_class/status/307506870850031616

_______________________________________________
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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
New patches on top of
<https://github.com/daxim/dbix-class/commits/master>.

> I wonder whether this should not mention DBIx::Class::Schema::Loader
> from the start.
With 974c7e5, the synopsis then has such a mention.

> hope we get some feedback
> from other folk versed in doc-writing
I got valuable feedback after reminding on irc. I'm sorry, I don't know
how to work the GH review feature so that it creates a forward link to
the commit, I hope I have done it right by just reading the info and
making a new one, backlinking to the review page. The result is
3a93a5e1cc. When rebasing onto master, you may fixup/squash this into
974c7e53e3.

I decided to not include the alternative way to update and delete via
row object accessors/methods because I feel that's too much for the
scope - I want a newcomer to be able to have a first feeling of success
after a very short time, and balance every side-step against the risk
of not achieving the goal. It does say "minimum amount of code" in the
intro. The row object alternatives are still explained in the main
docs, in ::Tutorial, in ::SQLHackers, in the book for the approach of
structured learning that comes afterwards, when the newcomer is on the
proverbial hook.

> Not merged. While I like the idea, I am not sure if mentioning
> DBIC::Row DBIC::Rel::Base (which is about to go away soon... I
> hope... I really do) is a good idea. Especially given that we have
> https://metacpan.org/module/DBIx::Class::Manual::ResultClass#INHERITED-METHODS.
It's not the problem you think it is. The docs patch does and must
reflect current reality. Worry about changing that when the time
actually comes. Of course, one could reword it to indirectly refer to
e.g. "the first two classes in the inherited methods list" or somesuch,
but that can silently/unnoticably become a dangling link
when ::Manual::ResultClass gets reorganised.

The explicit mention is better because it creates an obvious mode of
failure: when ::Rel::Base is removed, the author hopefully acks through
the whole source and sees this needs an update. Even if that is missed
and the distro ships with that broken link going nowhere, eventually a
reader notices and reports.

> Also I would recommend changing L<SQL::Abstract> to
> L<SQL::Abstract|SQL::Abstract/WHERE CLAUSES>.
Done in 7923f7c1b5. When rebasing onto master, you may fixup/squash
this into cc3ad5941e.

> Perhaps we should have a separate test-less
> DBIx::Class::ExtendedManual dist which is a direct dependency of
> DBIx::Class?
++ to that

_______________________________________________
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@...

signature.asc (853 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Peter Rabbitson-2
On Thu, Apr 04, 2013 at 08:36:53AM +0200, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 wrote:
> New patches on top of
> <https://github.com/daxim/dbix-class/commits/master>.
>
> > I wonder whether this should not mention DBIx::Class::Schema::Loader
> > from the start.
> With 974c7e5, the synopsis then has such a mention.

I meant more of a "this is how you do it in 30 seconds without reading
on the vagaries of result definitions". Given that this is a quick-start
guide it kinda seems apt. And by mention I mean simply the CLI dbicdump
oneliner and a link to SL. Again - just a suggestion, maybe it is out of
scope.

> > hope we get some feedback
> > from other folk versed in doc-writing
> I got valuable feedback after reminding on irc. I'm sorry, I don't know
> how to work the GH review feature so that it creates a forward link to
> the commit, I hope I have done it right by just reading the info and
> making a new one, backlinking to the review page. The result is
> 3a93a5e1cc. When rebasing onto master, you may fixup/squash this into
> 974c7e53e3.

I will leave it to castaway to comment on this one. The only thing that
is technically incorrect is that: "The first four arguments are the same
as for L<DBI/connect>" - the hash takes extra DBIC args directly if one
so wishes. But it probably doesn't matter for a quick-start.

> > Not merged. While I like the idea, I am not sure if mentioning
> > DBIC::Row DBIC::Rel::Base (which is about to go away soon... I
> > hope... I really do) is a good idea. Especially given that we have
> > https://metacpan.org/module/DBIx::Class::Manual::ResultClass#INHERITED-METHODS.
> It's not the problem you think it is. The docs patch does and must
> reflect current reality.

Right... and current reality is that folks look at ::Row, and decide it
is the base class and never look further on. This was the whole reason
behind constructing ::Manual::ResultClass - to highlight ::Row is just a
small part of the entire set. This is something SineSwiper should wheigh
in on.

> The explicit mention is better because it creates an obvious mode of
> failure: when ::Rel::Base is removed, the author hopefully acks through
> the whole source and sees this needs an update. Even if that is missed
> and the distro ships with that broken link going nowhere, eventually a
> reader notices and reports.

To reiterate - I am not worried about broken doclinks (we have soooo
many). I am worried about giving the user a skewed perspective on where
the methods for their Result class come from.

> > Perhaps we should have a separate test-less
> > DBIx::Class::ExtendedManual dist which is a direct dependency of
> > DBIx::Class?
> ++ to that

Well... Daxim, Abraxxa, Castaway, SineSwiper - who wants to tackle that?
This way we get the reference manual remain in core (and get updated
with code) and the tutorials etc being maintained separately (which is
safe given our commitment to backwards comp).

Cheers


_______________________________________________
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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Jess Robinson
In reply to this post by Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯

Hey, this is partly a response to this email, and partly to the one from  
March 24th (trying to catch up!)

General thought though, if the issue (as it appeared to be) was that you  
hadn't seen/found Tutorial and SQLHackers, then wouldn't it be more useful  
to set about improving these and making them more visible, than making  
another file which will also get lost in the noise?

I'm not a fan of the idea to get them all using the exact same schema  
classes, as that doesn't give much variance. Each is a separate doc for  
teaching in its own way, or at least that was the plan. I don't really  
understand the reasoning for doing this, can you explain it?

As to the previous comment somewhere that there's room for a whole bunch  
of tutorials by lots of people.. Maybe, but not in the DBIC docs  
themselves, that would just be confusing! There's plenty of room on the  
website though... Dammit, must get that updated... volunteers? ;)

On Thu, 04 Apr 2013 07:36:53 +0100, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <[hidden email]>  
wrote:

> New patches on top of
> <https://github.com/daxim/dbix-class/commits/master>.
>
>> I wonder whether this should not mention DBIx::Class::Schema::Loader
>> from the start.
> With 974c7e5, the synopsis then has such a mention.
>
>> hope we get some feedback
>> from other folk versed in doc-writing
> I got valuable feedback after reminding on irc. I'm sorry, I don't know
> how to work the GH review feature so that it creates a forward link to
> the commit, I hope I have done it right by just reading the info and
> making a new one, backlinking to the review page. The result is
> 3a93a5e1cc. When rebasing onto master, you may fixup/squash this into
> 974c7e53e3.
>
> I decided to not include the alternative way to update and delete via
> row object accessors/methods because I feel that's too much for the
> scope - I want a newcomer to be able to have a first feeling of success
> after a very short time, and balance every side-step against the risk
> of not achieving the goal. It does say "minimum amount of code" in the
> intro. The row object alternatives are still explained in the main
> docs, in ::Tutorial, in ::SQLHackers, in the book for the approach of
> structured learning that comes afterwards, when the newcomer is on the
> proverbial hook.

This is one of those "people do it differently" things. What are we  
actually trying to teach users? I would hope/assume its how to use DBIC as  
a backend for your objects, and not how to use it to talk to your  
database. There's a subtle difference. In the world of objects, and  
certainly in most of my DBIC-using code, I use $row->update 20x more often  
than $resultset->update. Your explanation doesn't really explain why one  
is preferable to the other, you could replace the ResultSet ones with the  
Row ones, and the above comment would still completely apply.

>> Not merged. While I like the idea, I am not sure if mentioning
>> DBIC::Row DBIC::Rel::Base (which is about to go away soon... I
>> hope... I really do) is a good idea. Especially given that we have
>> https://metacpan.org/module/DBIx::Class::Manual::ResultClass#INHERITED-METHODS.
> It's not the problem you think it is. The docs patch does and must
> reflect current reality. Worry about changing that when the time
> actually comes. Of course, one could reword it to indirectly refer to
> e.g. "the first two classes in the inherited methods list" or somesuch,
> but that can silently/unnoticably become a dangling link
> when ::Manual::ResultClass gets reorganised.

I'm not sure what this is about, but I agree with the general "document  
whats there NOW", remove/change it later if/when it changes. Too much  
planning ahead for changes that may not emerge is wasteful, and the change  
may turn out to be not what we expected.

Unless of course riba's "soon" means "has been implemented and I'm going  
to merge it before this document is done" ;)

>
> The explicit mention is better because it creates an obvious mode of
> failure: when ::Rel::Base is removed, the author hopefully acks through
> the whole source and sees this needs an update. Even if that is missed
> and the distro ships with that broken link going nowhere, eventually a
> reader notices and reports.
>
>> Also I would recommend changing L<SQL::Abstract> to
>> L<SQL::Abstract|SQL::Abstract/WHERE CLAUSES>.
> Done in 7923f7c1b5. When rebasing onto master, you may fixup/squash
> this into cc3ad5941e.
>
>> Perhaps we should have a separate test-less
>> DBIx::Class::ExtendedManual dist which is a direct dependency of
>> DBIx::Class?
> ++ to that

First we need to figure out how to smack metacpan around the head for not  
displaying/acknowledging the existance of .pod-only docs.. It may just  
work with .pm files that only have POD in? I like the ability to  
distribute and update the manual separately, and have it a dependency of  
DBIC itself, that seems to cover both worlds.

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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Peter Rabbitson-2
On Tue, Apr 09, 2013 at 01:20:33PM +0100, Jess Robinson wrote:

>
> >>Not merged. While I like the idea, I am not sure if mentioning
> >>DBIC::Row DBIC::Rel::Base (which is about to go away soon... I
> >>hope... I really do) is a good idea. Especially given that we have
> >>https://metacpan.org/module/DBIx::Class::Manual::ResultClass#INHERITED-METHODS.
> >It's not the problem you think it is. The docs patch does and must
> >reflect current reality. Worry about changing that when the time
> >actually comes. Of course, one could reword it to indirectly refer to
> >e.g. "the first two classes in the inherited methods list" or somesuch,
> >but that can silently/unnoticably become a dangling link
> >when ::Manual::ResultClass gets reorganised.
>
> I'm not sure what this is about, but I agree with the general
> "document whats there NOW", remove/change it later if/when it
> changes. Too much planning ahead for changes that may not emerge is
> wasteful, and the change may turn out to be not what we expected.
>
> Unless of course riba's "soon" means "has been implemented and I'm
> going to merge it before this document is done" ;)

It's not exactly "planning ahead", it's more of a "there is already
stuff to work around *precisely* this problem". SineSwiper commented
further here [1] (see 4th reply-hunk). The ::Manual::ResultClass has
been on CPAN for several months now [2], introduced/linked up by [3].
*This* is what I meant by "not sure it is a good idea to promote X".
Reiterated it here as well [4] (3rd reply hunk)

Cheers

[1] http://grokbase.com/t/sc/dbix-class/132r6q21ag/the-apparent-complexity-of-it-all#20130404lxvelgj6chdkbkh5boimbr3paa
[2] https://metacpan.org/module/RIBASUSHI/DBIx-Class-0.08210/lib/DBIx/Class/Manual/ResultClass.pod
[3] https://github.com/dbsrgits/dbix-class/commit/3d4c5a8439
[4] http://grokbase.com/t/sc/dbix-class/132r6q21ag/the-apparent-complexity-of-it-all#20130404bjtf2hk4wcozkvf7nkspe6imke

_______________________________________________
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@...
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "the apparent complexity of it all"

Peter Rabbitson-2
In reply to this post by Jess Robinson
On Tue, Apr 09, 2013 at 01:20:33PM +0100, Jess Robinson wrote:
>
> First we need to figure out how to smack metacpan around the head
> for not displaying/acknowledging the existance of .pod-only docs..
> It may just work with .pm files that only have POD in?

Butchering dists to please the substandard metacpan is not really
acceptable in my eye ;) I will be talking to ANDK and xdg about a formal
definition of how this should work this weekend.

Cheers


_______________________________________________
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@...
Loading...