On 7 May 2015 at 09:31, Neil Bowers <neil.bow...@cogendo.com> 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 / search.cpan.org, > 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: > 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. > 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. -- Kent *KENTNL* - https://metacpan.org/author/KENTNL
