-
Notifications
You must be signed in to change notification settings - Fork 560
Google Season of Docs 2021 project proposals
This document presents a project proposed by The Perl Foundation for Google's 2021 Season of Docs program. It was submitted to GSoD on March 26, 2021.
Perl is a free, open-source, general-purpose programming language originally developed by Larry Wall in the 1980s. Fast, flexible, and expressive, Perl quickly found its way onto just about every Unix-derived operating system (and then some).
During the 1990s, Perl’s ubiquity and ease of use played an integral role in the explosive growth of the infant Web. Today, Perl enjoys ongoing maintenance and development thanks to a core team of volunteers. It remains a part of countless computers' internal toolkits, and continues to power software including critical operating system features, websites of every sort, and myriad creative hobby projects.
In early 2021, the Perl project adopted a new style guide for its own dizzyingly voluminous documentation, and began to organize a new docs team. Perl’s participation in Google’s 2021 Season of Docs is part of this new effort.
Full disclosure: this overtly adapts one of GSoD’s sample project ideas. But it’s such a good idea, and so applicable to Perl, that we couldn't help but pick it up and make it our own.
Perl has a lot of documentation.
If you install the latest version of Perl on your computer, you’ll end up with around 100 new Unix man pages of varying length. These include a nine-part FAQ, and a function reference which all by itself contains over 200 additional entries. (You can also browse Perl's documentation on the web.)
None of this is surprising when you consider Perl’s history stretching into the previous millennium; features pile on features, over the years, and so goes the documentation. But while every sentence in Perl’s reams of docs might be technically accurate, the whole colllection is confoundingly labyrinthine to veteran Perl programmers—and utterly impenetrable to new users.
What Perl needs now, as it prepares for its first major-version increase since the 1990s, is a thorough audit of all this documentation by a focused technical writer. We need help identifying the most urgent needs of Perl’s documentation in order to make it accessible and friendly to new programmers--while remaining a comprehensive and convenient reference that draws on its own deep history.
This project includes the following goals:
- A comprehensive audit of Perl's documentation. We expect this two fall into two major categories:
- A thorough review of the documentation's content, all hundred-ish man pages of it (including that enormous function reference).
- An equally thorough review of the documentation's presentation, with an eye to its organization and discoverability. This includes not just its distributed man pages but its presence and availability on the web.
- Creation of a detailed "gap analysis" examining the difference (and the distance) between the present state of Perl's documentation, and the ideally organized, newcomer-friendly documentation called for by the new Perl style guide.
- Delivery of a roadmap of discrete, actionable steps that the Perl project can take to bridge that gap.
- Publication of the output of the previous two steps, hiring additional art and design resources as needed.
The project's goals do not include:
- Direct editing or revision of any of Perl's constituent documentation (a.k.a. "doc patches").
- Any changes made to the websites or other public resources that host, publish, or otherwise make available Perl's documentation.
That said, we do expect the roadmap--the ultimate deliverable of this project--to lead directly to many further projects fitting the above two descriptions.
We estimate the total time required to complete this project as between three and six months.
While the writer should ideally have experience in auditing documentation and comfort with reading programming-language docs, they need not have prior expertise with Perl. Given the project's interest in improving approachability for new users, an outsider's perspective might even prove advantageous here.
The project's dedicated volunteer support team so far includes Jason McIntosh and Dan Book, the latter of whom created Perl's official documentation website.
The hired writer will have access to The Perl Foundation's own Slack during the project, giving them direct access to various Perl subject-matter experts also interested in this project's success.
Perl, as a long-lived open-source project, has only very recently begun to consider the maintenance and improvement of its own documentation as a discrete sub-project. Prior to 2021, it has never considered metrics based on documentation quality alone. As such, we feel we can set rather modest qualifiers for initial success.
We shall set, as our success-metric, the Perl community's completion of at least two of this project's initial recommended actions within six months of the report's publication.
This project's budget exists mainly to support a single expert who will intensely study a very large corpus of documentation, and then deliver a report and recommendations about it. Other than some commissioning original art and design to decorate that final report, we don't anticipate any other significant resource costs.
We budget a cost of US$12,500, based on the following items.
| Item | Amount | Running Total | Notes |
|---|---|---|---|
| Audit and report | 10,000 | 10,000 | Paid to the technical writer hired for this project |
| Volunteer stipends | 500 | 11,500 | 3 volunteer stipends at 500 each |
| Art and design | 1,000 | 12,500 | Original artwork and other design accompanying the final publication |
| TOTAL | 12,500 |
The Perl Foundation has hired a technical writer for its GDoS 2021 project, which is now closed to further applications.
As requested by Season of Docs protocol, some additional background about the entities behind this project:
-
The Perl Foundation is the organization coordinating this project. TPF is a charitable nonprofit that with the mission of supporting the ongoing maintenance and development of Perl (as well as its "sister language" Raku).
TPF has worked with Google-sponsored projects several times via the Google Summer of Code program. It has also submitted an application to a previous Season of Docs iteration. The organization's collected experience with both of these programs led it to confidently adopt this project as a TPF-coordinated effort.
The primary liaison between this project and TPF will be Makoto Nozaki, the organization's Secretary.
The Perl Foundation's website is at https://www.perlfoundation.org.
-
Jason McIntosh, the lead organizer of this project, is a professional technical writer and the head of Perl's new documentation team.
In 2020, Jason accepted a grant from The Perl Foundation to create a new style guide for Perl. This process involved hiring a freelance editor to assist with the style guide's own style, and working with many community volunteers to assure the final document's quality through a "docs as code" review process.
The style guide will be officially released as part of Perl version 5.34, slated for mid-2021.
Jason also has extensive experience with project leadership, particularly as president and co-founder of Interactive Fiction Technology Foundation, a digital arts nonprofit. His website is at https://jmac.org.