Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD
2 views
Skip to first unread message
H.Merijn Brand
May 6, 2015, 11:00:05 AM5/6/15
to Peter Rabbitson, Perl QA, cpan-workers
On Wed, 06 May 2015 09:26:03 +0200, Peter Rabbitson
<riba...@cpan.org> wrote:
> On 05/06/2015 08:03 AM, Kent Fredric wrote:
> > This is something that has bothered me for a while.
> >
> > We have a lot of standards and guiding principles, but a lot of it is
> > all in our heads, wisdom one can only get by talking about it on
> > toolchain, and/or breaking things and getting yelled at.
> >
> > ...
> >
> > As such, I propose a very rudimentary idea:
> >
> > Toolchain
> >
> > This is the top namespace
> >
> > Toolchain::Standards
>
> First of all +1000 on the idea itself. I want to point out an
> alternative to the naming, simply because I have been thinking about
> something *very* similar for about 6 months now (and this email may in
> fact be the thing that gets me rolling).
>
> The toolchain is not the only thing that has a body of knowledge to be
> documented. All organizations have that. All individual projects have
> that. And *individual authors* have things they would want to document.
> Not because of vanity, but because it is much much much simpler to link
> to a piece of text, instead of rehashing an argument for the 100th time.
>
> Therefore I am urging you to think broader and go for:
>
> Policy - short blurb what is this about
> Policy::Org - short sub-blurb what is this about
> Policy::Org::P5P - pumpkin maitaned
> Policy::Org::Toolchain - joint maintainership
> Policy::Project
> Policy::Project::Moose
> Policy::Project::DBIC
> Policy::Author
> Policy::Author::AUTARCH - explicitly reserved (and non-squatable,
> PAUSE admins take action when needed)
> Policy::Author::RIBASUSHI
>
> Sorry for the sidetrack
One issue that bothers me is that *I* view CPAN as something to install
from. Unlike many others, I still use commands like "man" and "perldoc"
to read *installed* stuff. Works always, works everywhere (even when
there is not connection to the wicked world outside).
I share the sentiment David vented in another post:
* Who is each piece of information for?
* Where are they likely to look today?
* Are there existing documents that can be fixed/expanded?
If the proposed namespace is accepted, it is *unlikely* that that info
will be locally available. Why on earth would some Linux distro include
those documentation? Why would an end-user install it?
How much I admire this effort (+1000 as you say from me as well), I
think a structured HTML doc that people can download and read or PDF
with index will reach a wider audience.
Proof me wrong! Please!
--
H.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/
using perl5.00307 .. 5.21 porting perl5 on HP-UX, AIX, and openSUSE
http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/
<riba...@cpan.org> wrote:
> On 05/06/2015 08:03 AM, Kent Fredric wrote:
> > This is something that has bothered me for a while.
> >
> > We have a lot of standards and guiding principles, but a lot of it is
> > all in our heads, wisdom one can only get by talking about it on
> > toolchain, and/or breaking things and getting yelled at.
> >
> > ...
> >
> > As such, I propose a very rudimentary idea:
> >
> > Toolchain
> >
> > This is the top namespace
> >
> > Toolchain::Standards
>
> First of all +1000 on the idea itself. I want to point out an
> alternative to the naming, simply because I have been thinking about
> something *very* similar for about 6 months now (and this email may in
> fact be the thing that gets me rolling).
>
> The toolchain is not the only thing that has a body of knowledge to be
> documented. All organizations have that. All individual projects have
> that. And *individual authors* have things they would want to document.
> Not because of vanity, but because it is much much much simpler to link
> to a piece of text, instead of rehashing an argument for the 100th time.
>
> Therefore I am urging you to think broader and go for:
>
> Policy - short blurb what is this about
> Policy::Org - short sub-blurb what is this about
> Policy::Org::P5P - pumpkin maitaned
> Policy::Org::Toolchain - joint maintainership
> Policy::Project
> Policy::Project::Moose
> Policy::Project::DBIC
> Policy::Author
> Policy::Author::AUTARCH - explicitly reserved (and non-squatable,
> PAUSE admins take action when needed)
> Policy::Author::RIBASUSHI
>
> Sorry for the sidetrack
One issue that bothers me is that *I* view CPAN as something to install
from. Unlike many others, I still use commands like "man" and "perldoc"
to read *installed* stuff. Works always, works everywhere (even when
there is not connection to the wicked world outside).
I share the sentiment David vented in another post:
* Who is each piece of information for?
* Where are they likely to look today?
* Are there existing documents that can be fixed/expanded?
If the proposed namespace is accepted, it is *unlikely* that that info
will be locally available. Why on earth would some Linux distro include
those documentation? Why would an end-user install it?
How much I admire this effort (+1000 as you say from me as well), I
think a structured HTML doc that people can download and read or PDF
with index will reach a wider audience.
Proof me wrong! Please!
--
H.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/
using perl5.00307 .. 5.21 porting perl5 on HP-UX, AIX, and openSUSE
http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/
http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/
Kent Fredric
May 6, 2015, 3:00:01 PM5/6/15
to H.Merijn Brand, Peter Rabbitson, Perl QA, cpan-workers
Generally, with HTML, if I want to read HTML, I need a browser. Having the HTML on disk there just serves as an annoyance factor while I tell my OS to tell my browser to open the file. ( To contrast with "perldoc Foo" or <!mcpan foo> in my search bar, needing to locate an ABSPATH first is a bit annoying )
Generally that implies I have internet, and so a website ( such as metacpan ) is an ideal Go-To.
I would not be opposed to HTML and PDF renditions of said policies being available, the PDF is of course more likely to be amenable for people who just want to read it on their phone/kindle/whatever.
And you could, perhaps, periodically aggregate the Policy::<> stuff docs published to CPAN and format them to a single doc and potentially ship that with perl .... but I find it hard to imagine P5P wants to elevate "toolchain + CPAN policies" to "part of perl itself" level.
I find it hard to imagine any of this would be integrated with perl itself, in any way, no matter how it was formatted, because a large amount of the concerns presented don't pertain to "Perl itself", but to the CPAN Ecosystem in general.
0 new messages