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ɪᴇᴄᴋᴏᴡ 迪拉斯 <da...@cpan.org> wrote:

New patches on top of

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

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


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

Reply via email to