Skip Menu |
 

This queue is for tickets about the DBIx-Class CPAN distribution.

Report information
The Basics
Id: 83711
Status: resolved
Priority: 0/
Queue: DBIx-Class

People
Owner: Nobody in particular
Requestors: MITHALDU [...] cpan.org
Cc:
AdminCc:

Bug Information
Severity: (no value)
Broken in: (no value)
Fixed in: 0.08210



Subject: make it easier to find out where to start reading the docs
Download (untitled) / with headers
text/plain 494b
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.
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>
Download (untitled) / with headers
text/plain 1.2k
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.
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>
Download (untitled) / with headers
text/plain 1.8k
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
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
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>
Download (untitled) / with headers
text/plain 526b
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
Download (untitled) / with headers
text/plain 714b
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.
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>
Download (untitled) / with headers
text/plain 504b
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
Show quoted text
> With that, this ticket is done i think. Thank you. :)
Thank you! Cheers
Download (untitled) / with headers
text/plain 199b
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.
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>
Download (untitled) / with headers
text/plain 478b
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


This service is sponsored and maintained by Best Practical Solutions and runs on Perl.org infrastructure.

Please report any issues with rt.cpan.org to rt-cpan-admin@bestpractical.com.