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

On Wed, 06 May 2015 09:26:03 +0200, Peter Rabbitson
<[email protected]> 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/

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iQEcBAEBAgAGBQJVSik0AAoJEAOhR6E+XcCYB3cH/28S+dnRGe78k5HW783Lv3iO
TkVb3LGVJPC0vBIweNSdFDij6Sqj7eqpW3lM4W97EIM4j0gggOz1+9SvVyxbHg5f
5Ae7S+F5l8r/wT117zObo9ISPqY4GCEUI2Q47kiUQyvMwkUIpMIGsT3CJBwKiEXy
AQ7abjTyqbszUQTqYOrO+SYfyD+/3/UzJkWwAQxlCwqn5mPSh998uMBG2KA6Uw6e
ureJbJJJ8OzJp+75q+euJicOUBu/xOXow8qAaxp3Ic00QFnrWvNxTpj9TeiIlZjy
uFVfiLYd59E5Y3ubG82vwwZbqrR1iw82XeX0u6Fnr7DQBdI+/y0h11NL5VqBacI=
=5STj
-----END PGP SIGNATURE-----