Final Grant Report: Establishing Documentation Standards for the Perl 7 Era, October 2020
Fri, 06-Nov-2020 by
Jason A. Crome
edit post
<![CDATA[
Jason McIntosh has shared his progress on Perl 7 documentation standards for the month of October, and has delivered his final report on the grant:
*"October saw me very busy with the documentation standards project. After continuing the research I began in September, I spent much of the month writing a draft style guide to which I’ve given the filename “perldocstyle.pod”. Per my project proposal, I did seek comment on it from both within and outside the Perl community; this included my hiring a freelance style-guide editor to review the document.*
*"Midway through the month, I shared a request-for-comments report with P5P, including a couple of examples where I apply the proposed standards two two extant Perl man pages. This is at https://jmac.org/misc/perldoc/. In that RFC, I also propose the creation of a new documentation-focused sub-project within the larger Perl project, which would have its own dedicated team or manager. Obviously, I’m keeping the deliverables of this project scoped to just the style guide—but since I noticed that literally every project other than Perl that I visited during my research paired its style guide with a dedicated documentation team, I felt obliged to attach this recommendation to the project at hand.*
*"At month’s end, I submitted perldocstyle.pod as a pull request to the Perl project, proposing it as a new porting document. I have responded to code-review comments that porters have offered so far, and intend to continue working with P5P to see this file through to whatever its ultimate fate in the Perl repository might be. I’ve meanwhile declined to make additional pull requests from my updated-document examples, since doing so before these new standards’ ratification (via permanent acceptance into the repository) seems premature.*
*"As such, I consider this project delivered.*
*"Feedback from the community has been quite positive. Most people who have commented on the proposal express support for a focused documentation project within Perl. Several people stated a willingness to be part of whatever documentation-focused sub-project might result. Lively discussion and debate occurred on the P5P mailing list over the specifics of some of the proposed standards, which I take as a positive sign that Perl’s present stewards care very much about the quality of the language’s core documentation, and wish to actively improve it rather than simply let it passively accrue."*
]]>
Comments (0)
