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

[Jess Robinson]

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ɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim at cpan.org>  
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