[Dbix-class] RFC: Documentation/manual improvements

[Ash Berlin]

Matt S Trout wrote:
> As of 0.06, we're doing substantially better documentation-wise due to the 
> sterling efforts of a substantial number of contributors. But - getting all 
> the interfaces documented, arguments, return values etc. included is a 
> no-brainer. A more interesting question is - what took you a while to get your 
> head round conceptually, and what features did you find incredibly useful once 
> you were using them but hard to get up and working in the first place?
>
> Basically, what additional stuff to we need under the Manual::* namespace to 
> make it easier for both newbies and more experienced users to get the most out 
> of DBIx::Class with the least flailing/source-diving required? Comments here - 
> and if you're a relatively new user *please* pitch in, even if it's just a 
> couple of lines: The newer you are to the package, the better a perspective 
> you'll have on where the introduction/explanation stuff falls down.
>
>   
For me it was Relationships - I kept coming at them from the 'wrong' side

One particular example where i got it wrong:

I had a Group table with a leader column which contains the user ID of 
said leader. My initial thoughts on how to add this relation were to use 
a has_one rel - i.e. a group has one leader (when in fact the correct 
rel should be leader belongs to User)

Not sure how to improve this, but this is the area where I had the most 
trouble

Ash