Proposal to create a Perl Documentation Team

Dear Porters,

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.

MISSION STATEMENT

"The Perl Documentation Team, a sub-group of Perl 5 Porters, oversees the quality, accessibility, and maintainability of Perl's core documentation."

Some definitions

"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.

PERSONNEL

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.

RESOURCES

Mailing list

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.

Real-time chat

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.

Funding

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.

I agree with all of these points, and will be willing to volunteer to help clean-up and modernize the Perl docs.

That said I think we should modify the Accessibility section with a focus on getting the documentation more novice friendly as that will be a large part of the Perl 7 audience.

I also think that the documentation should be primarily targeted at the web (HTML) as I believe that is the way *most* documentation is consumed. Certainly maintain CLI/POD documentation, but that should be a secondary concern in 2020.

- Scott

Hmmm, I must have missed that. Damn. This is Important Stuff.

You may consider my splattering of comments on the PR to be my application to be a volunteer :-)

-- 
David Cantrell | Cake Smuggler Extraordinaire