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
Kent Fredric
May 7, 2015 06:15
Re: Documenting best practices and the state of ToolChain guidelinesusing CPAN and POD
Message ID:
On 7 May 2015 at 09:31, Neil Bowers <> wrote:

> Please please please, let’s not put this on CPAN. There are enough abuses
> of CPAN already. It’s a comprehensive archive of Perl, not everything in
> any way related to Perl. Plus I wouldn’t want to constrain this sort of
> documentation to pod, and how it’s presented on MetaCPAN /,
> which is what we’d effectively be talking about.

Agreed. POD is a peculiar syntax. However, markdown in practice is not much
better. In terms of features, the only things it does better from memory
are: Embedding images is native instead of requiring a =for html section,
and it has native tables support, which I may have used once.

IMHO a significant amount of POD suck is POD is written to emit POD that
renders the way MAN pages render, so of course, every POD has the first 4
lines with the standard =head1 NAME ... =haed1 VERSION ... =head1 SYNOPSIS,
and that I believe primes a way of thinking that leads to bad
documentation. Its a standard we adhere to, and I play along with, but I
feel its wrong every time I see it. </sidetrack>

> If there were a canonical source of information related to toolchain etc,
> then plenty of things on CPAN would link to it in their SEE ALSO sections,
> but it really doesn’t have to be *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.

The primary reason for this is really straight forward.

1. The wikis available in Perl are not great.
2. We don't want to use PHP
3. MediaWiki is not that great either, though its still the best there is.

> 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,

Again, my point was not so much that "markdown is evil", but "Browser based
editing is awful", and "The tools at our disposal for working with texts we
can only edit in our browser are few"

Similarly, there is a reason you rarely see people editing source code
directly on github, even though there is an option to do just that, its so
lacklustre vs "Edit it with a real editor and push it" few can be bothered
with it.

> IMHO :-) The advantage of a wiki is that it makes it very easy to
> contribute.
> And "easy to contribute" is highly subject to the wiki in question.
Keeping in mind any new wiki will need a *new* authorization model, and all
potential editors will have to sign up to said wiki.

For instance, one would not want anyone to be able to edit toolchain
policies, and you'd have a set list.

Additionally, one would not really even desire to edit the documents
directly, instead, you'd have drafts formed and discussion on the diffs and
submissions and changes. None of those workflows are available on wikis I
know of, but they're available right now via git + "its done, publish it".

Similarly, I would not imagine a wiki a good way to draft a book amongst
collaborators, its just not optimised for that usecase. Its optimised for
disorganized contributors changing stuff whenever they feel like it, where
review is an afterthought that happens sometimes when one other contributor
decides another contributor is wrong.

You could arguably have a workflow where all wiki content was drafted in
git first, and then some poor sod copy-pasted the text into the wiki form
and crossed their fingers. But that's a step backwards in terms of a
publishing platform.

Even some git based workflow that published to github pages with some
atrocity of jekyll would be better for this task IMHO than a wiki. ( This
is also a "moderately low barrier to get it working using existing
contribution systems" thing )

> There’s one domain that’s woefully under-used where this could live:
> 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.

At best, I think the argument you channel I can agree with is "CPAN might
not be the best place for these things". But the alternative places are
simply not in a shape where they can be used reasonably for these things in
any practical sense, and there is a lot of work in simply building any
infrastructure that might be more suitable than CPAN for these things.

And even then, that platform may only be amenable to the P5P/Toolchain
group, not extraneous groups like DBIC/Moose and/or Author oriented
policies like one author has already expressed a desire for.

And building such a platform that covers these concerns as well will take
yet more time and effort, and so you've got several orders of complexity
between where we are  and having documentation we can refer to usefully.

Whereas replication-via-CPAN is right up there on the list of the simplest
things that could work, because literally every part required to make it
function is already in place.


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About