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

[Peter Rabbitson]

On Fri, Feb 15, 2013 at 04:28:32PM -0500, Brendan Byrd wrote:
> On Fri, Feb 15, 2013 at 3:21 PM, Peter Rabbitson <rabbit+dbic at rabbit.us>wrote:
> 
> > 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.)

Third actually... :D

> 
> > *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 => 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/Class/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),

Yes, this is exactly how one should look at it, and this is one of the new
things 0.08240 introduces.

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

I am on board with re-iterating this in more places. If you have a specific
patchset in mind - just go for it. 

> > > DBIC, DBIx::Class, or L<DBIx::Class>?  What is "standard"?  I'm fine with
> > > simply DBIC (after an introduction to the term).  The link doesn't really
> > > 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?

Right, again - I am fine with both approaches. I just would like to 
point out that the linking is not that critical of an issue - the 
normalization of the content is the main goal here. Right?

Cheers