develooper Front page | perl.cpan.workers | Postings from May 2015

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

Thread Previous | Thread Next
From:
philippe.bruhat
Date:
May 6, 2015 22:10
Subject:
Re: Documenting best practices and the state of ToolChain guidelinesusing CPAN and POD
Message ID:
20150506221045.GA2345@localhost.localdomain
On Wed, May 06, 2015 at 10:31:36PM +0100, Neil Bowers wrote:
> > In that vein, we need some sort of Canon set of documentations, written and maintained by toolchain themselves, articulating how things /should/ be done as far as toolchain are concerned, without any sort of requirement that people adhere to it, unless they want to make toolchain happy.
> 
> +N
> 
> > As such, I propose a very rudimentary idea:
> > 
> > Toolchain
> > 
> > This is the top namespace 
> > 
> > Toolchain::Standards
> 
> Please please please, let’s not put this on CPAN. 
> 
> I’m no great fan of wikis, but I often thought it surprising that
> there isn’t a centralised wiki for Perl knowledge, a Perlipedia,
> if you will. It doesn’t have to be a wiki. It could be done via a
> github repo / github pages (yes, I did note your comment about markdown,
> but markdown is preferable to pod rendered via MetaCPAN, IMHO :-) The
> advantage of a wiki is that it makes it very easy to contribute.

github also makes it easy to contribute.

> There’s one domain that’s woefully under-used where this could live: perl.com
> 
> This isn’t a fully thought-out response, but I wanted to (a) offer
> support for the concept, and (b) plead that it not be done via CPAN.
> 

I have a proposal. I own and operate cpan.io, which is currently used
to host some CPAN-related score boards. Down the line, the goal it to
add more features using gamification to gently steer authors to into
becoming better CPAN-citizens.

It also has a "Reference" section, which currently contains one document:
Neil's history of CPAN. http://cpan.io/ref/history.html

I propose to gather scattered documents that live in various git
repositories (like the consensus documents pointed by David) and
automatically publish them there.

I'll run an experiment with with the few documents on the toolchain-site
repository, and we can see how that works.

Benefits:
- open source, hosted on github
- central location
- static site, easy to generate locally
- easy to add/remove repositories (and documents)
- any source format can be used, so long as it can be turned to HTML

-- 
 Philippe Bruhat (BooK)

 Honesty is its own reward. Dishonesty is its own punishment.
                                    (Moral from Groo The Wanderer #30 (Epic))

Thread Previous | 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