develooper Front page | perl.qa | Postings from May 2015

Re: Documenting best practices and the state of ToolChainguidelines using CPAN and POD

Thread Next
From:
H.Merijn Brand
Date:
May 6, 2015 14:46
Subject:
Re: Documenting best practices and the state of ToolChainguidelines using CPAN and POD
Message ID:
20150506164608.49e676b3@pc09.procura.nl
On Wed, 06 May 2015 09:26:03 +0200, Peter Rabbitson
<ribasushi@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/

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About