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

[Jess Robinson]

Yay, belated replies to ancient (ok, not really) messages!

On Fri, 15 Feb 2013 21:28:32 -0000, Brendan Byrd <Perl at resonatorsoft.org>  
wrote:

>> > 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?
>

Since you asked: We're not a "page" here, we're a reference doc. Most  
people (I assume) will be searching for the term they want, or clicking on  
a toc link at the top, if reading on the interwebs.. then just reading the  
section they want. Thus "just once at the top" doesn't really apply.

Having said that.. does DBIC itself really need linking at all, in the  
DBIC docs? If people don't know where they are, they've got bigger  
problems, I think ;)

NB: I haven't looked at the specific doc patch or commit, just responding  
to the ML question ;)

Jess