This website contains draft deliverables for the project Establishing Documentation Standards for the Perl 7 Era, written by Jason McIntosh in October 2020.
Feel free to discuss them within p5p or with the author. Jason may be contacted at jmac@jmac.org, or as jmac on IRC.
A Perl documentation style guide, “perldocstyle”, in two formats:
Sample modifications to extant core Perl documentation, applying some of the proposed style guide’s principles, and commenting upon each modificiation:
Actualizing these modifications would involve adapting them into two pull requests, comprising one commit for every commented set of changes. We leave that work as a separate exercise.
Before drafting the style guide, I researched how a number of Perl’s contemporaries among FOSS projects managed their own documentation. This included Python, Rust, Raku, and the Linux kernel project. With p5p’s assistance, I also gathered up what documentation-standards information Perl already has (e.g. perlpodstyle).
In every case outside of Perl, I found the presence of a separate sub-project focusing on the overall project’s documentation, with its own dedicated team members and other resources. Each of these also included a style guide, in one format or another. For example, Python dedicates a chapter of its developer’s guide to the topic, and Linux has a man page about it.
In grand Perl tradition, I enthusiastically lifted concepts and organizational techniques from all these style guides, while also mixing in my experiences updating Perl’s open and perlopentut documentation last spring. I received further guidance from Samantha Hamilton, a freelance documentation specialist I hired to review this work.
I recommend that p5p take further inspiration from the aforementioned projects through the establishment of a Perl documentation team, or at the very least create a documentation manager role that has the power to establish such a team in turn.
The resulting docs team would, from that point on, have primary responsibility for keeping Perl’s core documentation up-to-date, internally consistent, and newcomer-friendly. The team would treat the docs as an open-source project unto itself, even if it shares a code repository and release schedule with the larger Perl project. The team would also serve as the public’s primary point of contact–separate from p5p’s main channels–regarding questions about or contributions to Perl’s documentation.
I do not have specific advice for how to manage this team, outside of typical FOSS project patterns. Establishing this team with an eye to effectiveness and permanence would constitute a project unto itself. I would have interest in engaging with this proposed project upon the completed delivery of the initial standards project represented by the present document.