[DBIx-Class-Devel] DBIx-Class-0.08240-TRIAL docs review

[Brendan Byrd]

On Fri, Feb 15, 2013 at 3:21 PM, Peter Rabbitson <rabbit+dbic at rabbit.us>wro=
te:

> On Fri, Feb 15, 2013 at 02:17:13PM -0500, Brendan Byrd wrote:
> > See the latest commit to the topic/constructor_rewrite branch.  Mostly,
> > it's a lot of commas.
>
> I've never been good with these ;)
>

It's your second language.  You have a good excuse :)  Us stupid Americans
can barely speak/write one.  (Of course, Frew is in Texas, so he might know
Spanish.)

> *If L<collapsing|/collapse> is requested, there is an additional
> > requirement of **selecting enough data to make every individual object
> > uniquely identifiable.*
> >
> > I thought collapse =3D> 1 on prefetch.  Isn't it ALWAYS requested?
>
> But that's the point of collapse - you can use it standalone. Consider
> the bunch of "empty intermediates" here:
>
> https://metacpan.org/source/RIBASUSHI/DBIx-Class-0.08240-TRIAL/t/prefetch=
/manual.t#L227
>
> I also tried to explain this here, but if you missed it perhaps it needs
> more work:
>
> https://metacpan.org/module/RIBASUSHI/DBIx-Class-0.08240-TRIAL/lib/DBIx/C=
lass/ResultSet.pm#prefetch


Yeah, but it was in the PREFETCHING section.  It seemed redundant, but
given that you might set it manually, it's probably a good thing to have.
 (Over-communication is better than under-communication.)

Also, now that it just kinda hit me that collapse more or less equals
prefetch (minus the column selection), I'm thinking there should also be
some repetition of that within the collapse section.  Existing users know
what prefetch means, so putting the new feature out there and saying "hey,
we basically just exposed an attribute for prefetch, so they are related"
might click better with them.

(Yes, I realize I'm bring critical of repetition in one paragraph and
encouraging it in another.  Tech writing is weird like that...)


> > DBIC, DBIx::Class, or L<DBIx::Class>?  What is "standard"?  I'm fine wi=
th
> > simply DBIC (after an introduction to the term).  The link doesn't real=
ly
> > serve much of a purpose in this case.
>
> No standard, a standard would certainly be good. Note also that the
> POD in question was written about a year ago originally. I adjusted it
> to match a lot of the style decisions since, but missed the DBIC part.
>
> On the other hand if we are converging on something, L<DBIC|DBIx::Class>
> is probably the best way forward.
>

Maybe.  In Wiki editing, there are generally two schools of thought in
terms of linking.  Many follow the rule that if a term was introduced once
on a single page (in the beginning), it shouldn't be linked again, as too
many links cause the page to be ugly.  Others (including myself) believe
that it's inconvenient to hunt down the link and the thing should just be
linked as much as possible.

Given that we aren't Wikipedia and don't need to link to every single word,
I guess I'm fine with the latter.  On the other hand, I doubt anybody cares
about a link back to the main DBIC page.  Jess (or others), any opinions on
that?

-- =

Brendan Byrd <Perl at ResonatorSoft.org>
Brendan Byrd <BBYRD at CPAN.org>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/dbix-class-devel/attachments/201302=
15/d2ec0b98/attachment.htm