[Dbix-class] "the apparent complexity of it all"

[Peter Rabbitson]

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