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
<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@lists.scsys.co.uk
