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:
David Golden
Date:
May 6, 2015 14:29
Subject:
Re: Documenting best practices and the state of ToolChain guidelinesusing CPAN and POD
Message ID:
CAOeq1c_B8z=sorOPBn51vjehzr5+dS_se5M=1ym3nfaRucaFYw@mail.gmail.com
On Wed, May 6, 2015 at 2:03 AM, Kent Fredric <kentfredric@gmail.com> wrote:

>
> And this creates substantial problems for discovery and recall, as well as
> having a significant point-of-failure if any of the individuals maintaining
> those auxiliary sites get eaten by a SIGBUS


"People can't find the information that's out there. Let's create a new
place to put information."

This is like the xkcd standards problem (https://xkcd.com/927/).

Before charging off down the path of using CPAN as a CDN because it's
there, I'd think really hard about these questions:

* Who is each piece of information for?
* Where are they likely to look today?
* Are there existing documents that can be fixed/expanded?

The problem with blindly throwing stuff like consensus agreements out there
is that a huge portion of it is of no use to anyone outside toolchain
maintainers and people who insist on knowing how tools work.

If people go looking for information and find irrelevant stuff, they'll
stop looking.  Information needs to be narrowly targeted or it's just more
noise.

Project documentation is probably best kept with the project.

Guidelines for new authors should probably build on guidelines we already
give (eg perlnewmod) -- partly to ensure that there isn't contradictory
information and partly because putting it in the core makes it canonical by
default.

FWIW, I think CPAN Testers has been very successful with
http://wiki.cpantesters.org/.  When someone has a question, I point them
there.  When I have some advice to add, I put it there.  I don't know if
that's the right model, but it's an idea.

And simultaneous, if not before, putting more information out there, I'd
look at all the places it is today and how much of it can be pruned down.
Here's a quick brain dump of places I'd look:

EUMM, MB and Test::More docs
http://learn.perl.org/
http://perldoc.perl.org/
http://www.cpan.org/misc/cpan-faq.html
https://pause.perl.org/pause/query?ACTION=pause_04about
http://perlmonks.com/?node=Tutorials#Modules-How-to-Create-Install-and-Use

I'm sure there are many more.

David

P.S. Regarding the bus factor of consensus agreements, while it may be
invisible, the PTG has them:
https://github.com/Perl-Toolchain-Gang/toolchain-site

-- 
David Golden <xdg@xdg.me> Twitter/IRC: @xdg

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