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=E2=80=99d=
 love to hear further feedback from p5p=E2=80=94and if the feedback =
proves swiftly positive, advice on next steps.

=3Dhead1 MISSION STATEMENT

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

=3Dhead2 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.

=3Dhead1 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.

=3Dhead2 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.

=3Dhead1 RESOURCES

=3Dhead2 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.

=3Dhead2 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.

=3Dhead2 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.
0
jmac
11/16/2020 9:25:02 PM
perl.perl5.porters 48252 articles. 1 followers. Follow

2 Replies
5 Views

Similar Articles

[PageSpeed] 49

--------------A0814AB840D9383167A386B6
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit

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

On 11/16/2020 1:25 PM, Jason McIntosh wrote:
> 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’d love to hear further feedback from p5p—and if the feedback proves swiftly positive, advice on next steps.
>
> =head1 MISSION STATEMENT
>
> "The Perl Documentation Team, a sub-group of Perl 5 Porters, oversees the quality, accessibility, and maintainability of Perl's core documentation."
>
> =head2 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.
>
> =head1 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.
>
> =head2 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.
>
> =head1 RESOURCES
>
> =head2 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.
>
> =head2 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.
>
> =head2 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.
>

--------------A0814AB840D9383167A386B6
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: 8bit

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <p>I agree with all of these points, and will be willing to
      volunteer to help clean-up and modernize the Perl docs.</p>
    <p>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 <b>most</b> documentation is consumed.
      Certainly maintain CLI/POD documentation, but that should be a
      secondary concern in 2020.<br>
    </p>
    <p>- Scott<br>
    </p>
    <div class="moz-cite-prefix">On 11/16/2020 1:25 PM, Jason McIntosh
      wrote:<br>
    </div>
    <blockquote type="cite"
      cite="mid:13FBA65A-F598-4A52-8AFD-6A64BE14D281@jmac.org">
      <pre class="moz-quote-pre" wrap="">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 (<a class="moz-txt-link-freetext" href="https://github.com/Perl/perl5/pull/18275">https://github.com/Perl/perl5/pull/18275</a>), 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’d love to hear further feedback from p5p—and if the feedback proves swiftly positive, advice on next steps.

=head1 MISSION STATEMENT

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

=head2 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.

=head1 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.

=head2 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.

=head1 RESOURCES

=head2 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.

=head2 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.

=head2 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.

</pre>
    </blockquote>
  </body>
</html>

--------------A0814AB840D9383167A386B6--
0
scott
11/16/2020 10:32:51 PM
On Mon, Nov 16, 2020 at 04:25:02PM -0500, Jason McIntosh wrote:

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

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

> 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???d love to hear further feedback from p5p???and if the feedback proves swiftly positive, advice on next steps.
> ...
> The docs team shall consist of one manager and a zero-or-greater number of other volunteers, at the manager's discretion.

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

-- 
David Cantrell | Cake Smuggler Extraordinaire

          All praise the Sun God
          For He is a Fun God
          Ra Ra Ra!
0
david
11/17/2020 12:03:36 PM
Reply: