-
Notifications
You must be signed in to change notification settings - Fork 560
Google Season of Docs 2021 project proposals
Hello! This wiki page is the “project proposal page” for Perl’s participation in the 2021 Google Season of Docs. This year's GSoD mandates that every participating organization create a public space to help discuss project ideas prior to the March 26 deadline--and this is that, for Perl.
This work is happening in coordination with The Perl Foundation.
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, and it remains a part of countless computers' internal toolkits.
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 it just might fits the bill almost as-written.
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 powerful reference that remembers its the rich history of its subject matter.
We wish to end up with a roadmap that describes specific, actionable ways that Perl’s docs need to change, and in what priority-order, to meet the goals set by the new style guide.
We want to transform to docs from their present teetering patchwork pile into a consistent, well-organized, and approachable body of work. The labor of all that revision will constitute a separate project—or, better stated, many future follow-up projects. This project will focus on indentifying the current documentation’s needs, describing them, and putting them into some sort of workable order.
If the roadmap directly results in at least two new Perl documentation projects commencing within six months of its delivery, we will consider this endeavor a success.
The tech writer taking on this project should feel comfortable with reading and reviewing programming language documentation, and feel confident about what makes for great docs.
Specific knowledge about and experience with auditing an existing body of documentation would be excellent, of course.
Prior expertise or even familiarity with Perl is not necessary. In fact, an outsider's viewpoint would prove advantageous to this project, better able to catch oddities too-easily overlooked by those who have marinated in this documentation for many years.
But if you do happen to already know Perl, that's good too!
Your main contact for this position is Jason McIntosh ([email protected]), the head of Perl’s nascent docs team.
The writer we hire for this role will have access to The Perl Foundation’s Slack, for which we’ll set up a special channel to discuss this project in a friendly chat environment with other helpful volunteers.
Other volunteers include Dan Book, who (among many other things!) set up the current Perl documentation website at perldoc.pl.
The final budget is TBD, but given the scope of this project I would expect to ask for the maximum that GSoD allows (US$15,000), with the majority going to the hired technical writer. A lesser amount would be reserved for commissioned design or artwork, as needed, as well as miscellaneous overhead costs. We would reserve the option to award modest stipends to the project's dedicated community volunteers, per GSoD rules.
To learn more about this project, please contact Jason McIntosh, or drop by the #docs IRC channel on irc.perl.org.
Feel free to add more project ideas here, if you happen to have write-access to this wiki--and in any event, you can contact Jason McIntosh, drop by the #docs IRC channel on irc.perl.org, or join the #season-of-docs channel in the Write the Docs Slack.
The deadline to submit a final project proposal to Google is March 26, 2021 at 18:00 UTC.