This document presents a project proposed by The Perl Foundation for Google's 2021 Season of Docs program.
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 for Perl’s documentation in order to make it accessible and friendly to new programmers. At the same time, it must remain a powerful reference that remembers the rich history of its subject matter.
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.
- Publishing and publicizing 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. The writer will, over the course of the project, have access to multiple dedicated volunteers as project coordinators, as well as membership in The Perl Foundation's own Slack for direct access to Perl subject-matter experts interested in this project's success. We estimate the total time required to complete this project as between three and six months.
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 have budgeted for 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 | ||
| | |||
| |
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 and his website is at https://jmac.org.