Bug #83711 for DBIx-Class: make it easier to find out where to start reading the docs

Fri Mar 01 10:56:34 2013 MITHALDU [...] cpan.org - Ticket created

Subject:

make it easier to find out where to start reading the docs

DBIx/Class.pm does have a link to DocMap, but that link comes after a quite lengthy synopsis and a lengthy description of DBIC. Moving that segment up in the file and titling it appropiately should help guide newbies towards the documentation, with a lower chance of them overlooking it and getting lost in the sco/metacpan chaos of file listing; and as such reduce the amount of people asking confused questions on IRC. The change is in the branch "docmap_move" if you wish to apply it.

Fri Mar 01 11:27:15 2013 ribasushi [...] leporine.io - Correspondence added

Subject:	Re: [rt.cpan.org #83711] make it easier to find out where to start reading the docs
Date:	Sat, 2 Mar 2013 03:27:04 +1100
To:	Christian Walde via RT <bug-DBIx-Class [...] rt.cpan.org>
From:	Peter Rabbitson <ribasushi [...] cpan.org>

On Fri, Mar 01, 2013 at 10:56:35AM -0500, Christian Walde via RT wrote: Show quoted text

> Fri Mar 01 10:56:34 2013: Request 83711 was acted upon. > Transaction: Ticket created by MITHALDU > Queue: DBIx-Class > Subject: make it easier to find out where to start reading the docs > Broken in: (no value) > Severity: (no value) > Owner: Nobody > Requestors: MITHALDU@cpan.org > Status: new > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=83711 > > > > DBIx/Class.pm does have a link to DocMap, but that link comes after a > quite lengthy synopsis and a lengthy description of DBIC. Moving that > segment up in the file and titling it appropiately should help guide > newbies towards the documentation, with a lower chance of them > overlooking it and getting lost in the sco/metacpan chaos of file > listing; and as such reduce the amount of people asking confused > questions on IRC. > > The change is in the branch "docmap_move" if you wish to apply it.

IMHO splitting the "Where to get help" section into "Where to get help" and "Where is the source", and then arranging stuff like follows would be better? "Where to get help" "Where to go next" "Where is the source" This is just a suggestion, if you believe your arrangement is better I have no problems applying this.

Fri Mar 01 11:27:18 2013 The RT System itself - Status changed from 'new' to 'open'

Fri Mar 01 12:15:42 2013 walde.christian [...] gmail.com - Correspondence added

Subject:	Re: [rt.cpan.org #83711] make it easier to find out where to start reading the docs
Date:	Fri, 01 Mar 2013 18:15:26 +0100
To:	MITHALDU [...] cpan.org, "Peter Rabbitson via RT" <bug-DBIx-Class [...] rt.cpan.org>
From:	"Christian Walde" <walde.christian [...] gmail.com>

Show quoted text

>> [...] Moving that >> segment up in the file and titling it appropiately should help guide >> newbies towards the documentation, with a lower chance of them >> overlooking it and getting lost in the sco/metacpan chaos of file >> listing; and as such reduce the amount of people asking confused >> questions on IRC.

> > IMHO splitting the "Where to get help" section into "Where to get help" > and "Where is the source", and then arranging stuff like follows would > be better? > > "Where to get help" > "Where to go next" > "Where is the source" > > This is just a suggestion, if you believe your arrangement is better I > have no problems applying this.

While i'm very open to provide feedback and suggestions for splitting up the where to get help section, i think there's a small misunderstanding here. Yesterday i was being confused by relations in DBIC because i hadn't found the appropiate thing to read yet, caused by me not seeing an obvious starting point and thus resorting to grepping with metacpan and hoping for the best. I'm sure many other newbies run into similar problems. This change is meant to make it clear for someone who looks at DBIx::Class on sco or metacpan exactly where they need to start reading to learn DBIC and to do so in a way that has a minimum chance of people missing the starting point, by putting it directly under NAME. Thus, to provide more salient feedback on your exact question up there, i think it should be ordered like this: "Where to start?" "Where to find user resources?" "Where to find developer resources?" That would intuitively be the progression someone goes through when using DBIC: 1. learn, 2. deepen, 3. customize. Do you agree? If so i could look at DBIx/Class.pm again and make an additional commit with the secondary split. -- With regards, Christian Walde

Fri Mar 01 12:33:19 2013 ribasushi [...] leporine.io - Correspondence added

Subject:	Re: [rt.cpan.org #83711] make it easier to find out where to start reading the docs
Date:	Sat, 2 Mar 2013 04:33:03 +1100
To:	Christian Walde via RT <bug-DBIx-Class [...] rt.cpan.org>
From:	Peter Rabbitson <ribasushi [...] cpan.org>

On Fri, Mar 01, 2013 at 12:15:45PM -0500, Christian Walde via RT wrote: Show quoted text

> Queue: DBIx-Class > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=83711 > >

> >> [...] Moving that > >> segment up in the file and titling it appropiately should help guide > >> newbies towards the documentation, with a lower chance of them > >> overlooking it and getting lost in the sco/metacpan chaos of file > >> listing; and as such reduce the amount of people asking confused > >> questions on IRC.

> > > > IMHO splitting the "Where to get help" section into "Where to get help" > > and "Where is the source", and then arranging stuff like follows would > > be better? > > > > "Where to get help" > > "Where to go next" > > "Where is the source" > > > > This is just a suggestion, if you believe your arrangement is better I > > have no problems applying this.

> > While i'm very open to provide feedback and suggestions for splitting up > the where to get help section, i think there's a small misunderstanding > here. Yesterday i was being confused by relations in DBIC because i hadn't > found the appropiate thing to read yet, caused by me not seeing an obvious > starting point and thus resorting to grepping with metacpan and hoping for > the best. I'm sure many other newbies run into similar problems. > > This change is meant to make it clear for someone who looks at DBIx::Class > on sco or metacpan exactly where they need to start reading to learn DBIC > and to do so in a way that has a minimum chance of people missing the > starting point, by putting it directly under NAME. > > Thus, to provide more salient feedback on your exact question up there, i > think it should be ordered like this: > > "Where to start?" > > "Where to find user resources?" > > "Where to find developer resources?" > > That would intuitively be the progression someone goes through when using > DBIC: 1. learn, 2. deepen, 3. customize. > > Do you agree? >

That works for me too. My motive is for a user to see the "get to the chatroom here" on the first "frame" of the page on s.c.o. or metacpan. Go for it

Mon Mar 04 08:01:37 2013 walde.christian [...] gmail.com - Correspondence added

Subject:	Re: [rt.cpan.org #83711] make it easier to find out where to start reading the docs
Date:	Mon, 04 Mar 2013 14:01:22 +0100
To:	"Peter Rabbitson via RT" <bug-DBIx-Class [...] rt.cpan.org>
From:	"Christian Walde" <walde.christian [...] gmail.com>

On Fri, 01 Mar 2013 18:33:19 +0100, Peter Rabbitson via RT <bug-DBIx-Class@rt.cpan.org> wrote: Show quoted text

> That works for me too. My motive is for a user to see the "get to the > chatroom here" on the first "frame" of the page on s.c.o. or metacpan. > > Go for it

I've adapted the relevant bits and written some prose. The changes are force-pushed into the same branch. I'm very unsure about how good these changes are, so please take a look and let me know if there are disagreeable parts. -- With regards, Christian Walde

Tue Mar 05 00:25:18 2013 ribasushi [...] leporine.io - Correspondence added

On Mon Mar 04 08:01:37 2013, walde.christian@gmail.com wrote: Show quoted text

> On Fri, 01 Mar 2013 18:33:19 +0100, Peter Rabbitson via RT > <bug-DBIx-Class@rt.cpan.org> wrote: >

> > That works for me too. My motive is for a user to see the "get to the > > chatroom here" on the first "frame" of the page on s.c.o. or metacpan. > > > > Go for it

> > I've adapted the relevant bits and written some prose. The changes are > force-pushed into the same branch. I'm very unsure about how good these > changes are, so please take a look and let me know if there are > disagreeable parts. >

I pushed docmap_move_ribas_version with multiple cleanups. See if you can live with this version and merge it to master if the case.

Tue Mar 05 06:07:19 2013 walde.christian [...] gmail.com - Correspondence added

Subject:	Re: [rt.cpan.org #83711] make it easier to find out where to start reading the docs
Date:	Tue, 05 Mar 2013 12:07:01 +0100
To:	"Peter Rabbitson via RT" <bug-DBIx-Class [...] rt.cpan.org>
From:	"Christian Walde" <walde.christian [...] gmail.com>

On Tue, 05 Mar 2013 06:25:22 +0100, Peter Rabbitson via RT <bug-DBIx-Class@rt.cpan.org> wrote: Show quoted text

> I pushed docmap_move_ribas_version with multiple cleanups. See if you > can live with this version and merge it to master if the case.

That looks great and you did exactly what i hoped for, namely clarifying the contribution bits. I fast-forwarded master to your branch and removed your remote branch marker. With that, this ticket is done i think. Thank you. :) -- With regards, Christian Walde

Tue Mar 05 06:20:26 2013 ribasushi [...] leporine.io - Correspondence added

Show quoted text

> With that, this ticket is done i think. Thank you. :)

Thank you! Cheers

Tue Mar 05 06:20:28 2013 ribasushi [...] leporine.io - Status changed from 'open' to 'patched'

Tue Mar 05 11:25:50 2013 MITHALDU [...] cpan.org - Correspondence added

Addendum: Pushed a branch called "better_rt_link", which changes the rt link in DBIx::Class to one that doesn't require a login. Please merge that to master if i didn't make an egregious oversight.

Tue Mar 05 11:25:53 2013 The RT System itself - Status changed from 'patched' to 'open'

Tue Mar 05 11:40:25 2013 ribasushi [...] leporine.io - Correspondence added

Subject:	Re: [rt.cpan.org #83711] make it easier to find out where to start reading the docs
Date:	Wed, 6 Mar 2013 03:40:06 +1100
To:	Christian Walde via RT <bug-DBIx-Class [...] rt.cpan.org>
From:	Peter Rabbitson <ribasushi [...] cpan.org>

On Tue, Mar 05, 2013 at 11:25:53AM -0500, Christian Walde via RT wrote: Show quoted text

> Queue: DBIx-Class > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=83711 > > > Addendum: Pushed a branch called "better_rt_link", which changes the rt > link in DBIx::Class to one that doesn't require a login. Please merge > that to master if i didn't make an egregious oversight.

Good catch. I changed the URL to https however - the less big brother knows - the better :D Cheers

Tue Mar 05 14:42:56 2013 ribasushi [...] leporine.io - Status changed from 'open' to 'patched'

Tue Apr 30 02:47:34 2013 ribasushi [...] leporine.io - Fixed in 0.08210 added

Tue Apr 30 02:47:35 2013 ribasushi [...] leporine.io - Status changed from 'patched' to 'resolved'