Re: Documenting best practices and the state of ToolChain guidelines using CPAN and POD

+2  And further, when we have that notification thing that lets people know
they have people using their stuff, when their module reaches a critical
number of things depending on it, we should recommend they link to it in
their POD, assuming they want to follow it.

On Tue, May 5, 2015 at 11:03 PM, Kent Fredric <[email protected]> wrote:

> This is something that has bothered me for a while.
>
> We have a lot of standards and guiding principles, but a lot of it is all
> in our heads, wisdom one can only get by talking about it on toolchain,
> and/or breaking things and getting yelled at.
>
> In that vein, we need some sort of Canon set of documentations, written
> and maintained by toolchain themselves, articulating how things /should/ be
> done as far as toolchain are concerned, without any sort of requirement
> that people adhere to it, unless they want to make toolchain happy.
>
> Python have something similar to what I propose, PEP standards. Shit, I
> think I even saw some group for PHP define some set of standards for
> certain things(!!!! They're learning and getting organised, quick, kill
> them before they breed)
>
> Its also sad we don't really have any canonicalised representation of any
> toolchain agreements that have been established at hackathons, they're
> basically invisible or hiding on individual members blogs. As is the best
> practices for various problems also hidden on various blogs ( see also
> version numbers should be boring )
>
> 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
>
> As such, I propose a very rudimentary idea:
>
> Toolchain
>
> This is the top namespace
>
> Toolchain::Standards
>
> This is an index of various standards and guidelines
>
> Toolchain::Standards::<name>
>
> Where <name> is \d{4}_\w+ , for example 0001_Versions
>
> Numericalization is intended to make it clear which standards are "newer"
> and which are "older" instead of just having a pure Alnum sort.
>
> Toolchain::Standards itself should be an index of the standards grouped
> under several headings, with a short brief under each.
>
> Understandably, this is not necessary for metacpan which will show
> abstracts naturally, but we may want briefs larger than a standard
> abstract, and we want to optimise for offline consumption also.
>
>
> There would also be a proviso for deprecating or suspending a standard if
> it fell out of use, and this organisation would also be helpful there.
>
> ( As well as having an index of articles that pertained to specific
> subjects and/or were decided on by various QAH groups ).
>
> Each of these standards though would be "Living" standards and would be
> updated as need be to reflect current working practices, and so deprecation
> of a document would only be a thing if the entire concept fell out of use,
> and it would otherwise simply be refurbished to be current.
>
> I would also like a space under Toolchain:: for documenting the results of
> various meetings / group discussions as a collective, and those articles
> would be largely write-once -> historical documents to serve as an easy
> reference point to show how various policies came to be over time ( Similar
> to perl5xxxdeltas )
>
> The Toolchain:: namespace itself does not seem to be taken, and if there
> is no opposition, I may start the ball rolling at some time by claiming the
> namespace.
>
> --
> Kent
>
> *KENTNL* - https://metacpan.org/author/KENTNL
>
>