On October 23, I shared an RFC for a proposed Perl core documentation style guide, as well as a related proposal to treat Perl's core docs as a discrete sub-project, with its own team. Both received an encouraging amount of positive response--including some lively, opinionated discussion about the finer points of documenting Perl, perfect topics for that as-yet-notional docs team.
And so, as a parallel task to the in-progress pull request for the style guide document (https://github.com/Perl/perl5/pull/18275), I'd like to more formally propose the formation of a Perl documentation team. My definition for this team, its mission, and its makeup follows. I love to hear further feedback from and if the feedback proves swiftly positive, advice on next steps.
"The Perl Documentation Team, a sub-group of Perl 5 Porters, oversees the quality, accessibility, and maintainability of Perl's core documentation."
"Perl's core documentation": This includes all the documentation that ships with Perl itself: stand-alone documents, function reference sections, and documentation attached to standard modules. (We recognize that the much of the latter doesn't exist within Perl's core source distribution; the docs team nonetheless monitors the state of these CPAN-based docs and actively makes recommendations to improve them as needed.)
"Quality": The obvious job. Responsible for the core docs staying up-to-date, consistently readable, and correct.
"Accessibility": Making sure that Perl's core docs are discoverable and navigable by all the language's users, new and old, across all relevant media. This includes the web.
"Maintainability": Treating the core docs as a proper FOSS concern, within the larger Perl project. Includes enthusiastically welcoming patches from the community, and making it easy for any interested reader to discover how they can contribute to the documentation project. Also includes working with p5p to make sure that docs stay synchronized with new Perl releases.
The docs team shall consist of one manager and a zero-or-greater number of other volunteers, at the manager's discretion.
Perl 5 Porters oversees the appointment of the manager role.
Do you have anyone in mind, jmac?
I volunteer myself, Jason McIntosh, to serve as the inaugural doc team manager, and I am ready to commence this role immediately.
The docs team should have a mailing list at the perl.org domain, with the manager having administrative access to it. (At least one other p5p member should have admin access as well.) The mailing list will serve as the unchanging bedrock communication layer for the team.
Initially, the team will also have a dedicated channel (#docs) on irc.perl.org. The manager may migrate this to other chat systems in the future at their own discretion.
When appropriate, the team will seek funding for specific projects or materials via TPF grant requests, just as with any other project in Perl-land. All docs team members otherwise serve on a volunteer basis.