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:
Kent Fredric
Date:
May 6, 2015 18:31
Subject:
Re: Documenting best practices and the state of ToolChain guidelinesusing CPAN and POD
Message ID:
CAATnKFBWKE8pR7JHZWodkbuCG4dz8VYLOveotvmrqBa6MCp5kg@mail.gmail.com
On 7 May 2015 at 02:28, David Golden <xdg@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

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