On 7 May 2015 at 02:28, David Golden <x...@xdg.me> wrote: > > This is like the xkcd standards problem (https://xkcd.com/927/). > > I was literally waiting with baited breath for that to be referenced as I wrote the original email :D
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? > * CPAN Authors primarily, but policies and guidelines should be authored in such a way darkpan authors may find them useful * Google, and what they search for presently returns substantial amounts of CPAN results https://encrypted.google.com/search?hl=en&q=cpan%20policy # moslty cpan https://encrypted.google.com/search?hl=en&q=cpan%20standard # mostly cpan https://encrypted.google.com/search?hl=en&q=cpan%20guide # exception to mostly cpan :P https://encrypted.google.com/search?hl=en&q=perl%20policy # 50/50 https://encrypted.google.com/search?hl=en&q=perl%20standard # a mixed bag with stackoverflow https://encrypted.google.com/search?hl=en&q=perl%20guide # learning material https://encrypted.google.com/search?hl=en&q=perl%20toolchiain%20policy # most relevant result so far ... 4th result is XDGs personal blog, though 3rd result is the lancaster consensus which is good. https://encrypted.google.com/search?hl=en&q=perl%20toolchiain%20guide # similar to above, but more CPAN results https://encrypted.google.com/search?hl=en&q=perl%20toolchain%20guide # similar to above https://encrypted.google.com/search?hl=en&q=cpan%20toolchain%20policy # aristotles blog take first place and there's a lot of similarairty to the perl toolchain results https://encrypted.google.com/search?hl=en&q=cpan%20toolchain%20standard # similar again https://encrypted.google.com/search?hl=en&q=cpan%20toolchain%20guide # similar again The overwhelming trends being: - CPAN - Personal Blogs - Deep in Github. - Stackoverflow * People may also be inclined to expect documentation pertaining to standards on CPAN. I personally was surprised that pumping "Lancaster" into MetaCPAN didn't give me a lot of relevant results. * Some of the existing documentation exists, but it is scattered, for instance, this article: http://www.dagolden.com/index.php/369/version-numbers-should-be-boring/ , really deserves to be in a more visible place, or something equivalent to it. Not as a binding law necessarily, but as guiding wisdom that people can simply refer to as "We follow this" amongst each other voluntarily, similar to how people presently use Perl::Critic policies, so that all people who follow the guidelines benefit from the cohesion. ( People are free to make various policies law within the code they control of course, and an external representation of those policies helps ) > 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. > Right. But presently, there is no obvious way to get this knowledge, or if you have one piece of said knowledge, an obvious way to read related knowledge. We presently rely on a system of people making a mistake, and then we discover it, we tell them using our tribal knowledge why its wrong, and there's no way for them to gloss over other such tribal knowledge that you don't know you need yet. At best, presently we can defer to peoples blogs on various things, and we have to have people who can remember which is on which blog to direct people to it. That much is very sub-optimal. > 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. > Right, but "Project" here often spans multiple cpan modules. As such the guidelines pertain to the host of modules directly in control of the people controlling key pieces in that project, but other people may still find the policies and guidelines useful to consume voluntarily for non-project related code. > > 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. > Right. This was partly my initial idea, but that has its limitations. Mostly, that a lot of these concerns are not "core" related. There are policies that apply to stuff in core. But its easy to see there are guidelines which would not be suitable as a P5P governed project. For instance, the versions article I'd imagine would not be accepted as part of core, because it being there would lend *too much* authority to the document. Policies pertaining to toolchain really is an external concern from "perl itself" It also would imply policy changes would be bound to perls release cycle, which might be fine for P5P policies, but it would largely be unacceptable for Toolchain. Additionally, some of this proposal is not really about establishing a standard, but simply providing a convenient model for standard publication. And namespaces like Policy::Author::RIBASUSHI are not just conjecture! Such a thing will, I'm sure, be a thing one day in one form or another. Such a system can't be made work if the policies in question are expected to be part of perl itself. > > 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. > Some of my objections there with exactly that ( I've poked a round a little ), start with the auth system being a bit strange. There are many advantages to using CPAN as a CDN in this regard, in that we have an established well tested way of delegating power to whoever should have publishing rights. The CDN-Via-CPAN mechanism also by default allows using our existing tools that we're familar with to formulate said policies, and do them via a consultation period and drafting prior to publication, using the existing git tools. I should also state that some of my objections to using external things to the CPAN infrastructure has been the cascade of bad experiences with using the external tools, especially in manners of authentication. ( For instance, I found blogs.perl.org a substantial pain to use when it was working, and the frequent issues with using it, and now the inability to log in and submit posts at all has all left a bad taste in my mouth. And bpo is not the first thing that has had this effect. Even RT makes me grind my teeth at least once every few days when it forgets I'm logged in, and I have to do a rodeo dance and log out when not logged in so that I can log in. Its fine past that, but that specific problem wears me down ) I also have objections to models that are just glorified multiplayer notepad. Textarea boxes and markdown are ok for doing comments and short documents, but I'm quickly wishing for a real text editor and hacking away in a browser text area makes me feel like a peasant in the dark ages wallowing in filth. ( And this is of course exacerbated by the available perl wiki's being lacklustre ) 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. > > Most of those are rather "tutorial" in nature. Not specifications / guidelines / policies. They are open ended structures that dictate the general nature of how to do something, which contrasts to the proscriptive "What you should not do at toolchain level" and "what you should do at toolchain level". For instance, an example document might be: Policy::Toolchain::003_MakefileLegacy Which entails the guidelines pertaining to toolchains desire to ensure Makefile.PL itself is portable and usable back to 5.006, giving justification for the goal, giving benefits and common problems one may find with achieving that goal, with some general techniques to achieve the goal. 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 > I don't see however why the website would have to be the sole carrier of this documentation. For comparison, I know dzil.org has a website, but I practically never visit it. -- Kent *KENTNL* - https://metacpan.org/author/KENTNL
