Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Perl's submission to Google Season of Docs 2021

GSoD 2021 Proposal: Audit Perl's documentation

This document presents a project proposed by The Perl Foundation for Google's 2021 Season of Docs program.

About Perl (and its docs)

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.

About this project

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.

The problem

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's scope

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.

Project personnel

At the time of this application, the project's organizer is in contact with a number of candidates for the technical writer role.

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.

Measuring 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.

Project budget

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

How to Apply

The Perl Foundation has hired a technical writer for its GDoS 2021 project, which is now closed to further applications.

Additional information

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 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.

@anirudhtavva

This comment has been minimized.

Copy link

@anirudhtavva anirudhtavva commented Apr 16, 2021

Hi,

I am ANIRUDH TPVS and I am very much interested in contributing to the Perl foundation as a technical writer. I have prior experience as technical writer as well as in auditing and writing documentations.

https://drive.google.com/drive/folders/1zo3SpO61ss03bu9EUtFpGwENHoIXnwrP?usp=sharing

Please see the above attached link which contains my CV and some of my writing works.

My email address: anirudhtpvsp@gmail.com

@Rohitesh-Kumar-Jain

This comment has been minimized.

Copy link

@Rohitesh-Kumar-Jain Rohitesh-Kumar-Jain commented Apr 24, 2021

Hi Team,

I am a past participant of Google Season of Doc's 20 program, I completed my SoD'20 project with Global Wordnet Association (tech writer name: Kumar), and this year interested in giving back to the program by participating as a Volunteer and mentoring tech writers.

Best,
Rohitesh K Jain

@gupta-niharika

This comment has been minimized.

Copy link

@gupta-niharika gupta-niharika commented Apr 25, 2021

Hi, 😄
I am Niharika Gupta, and I am very keen to contribute to Perl foundation's documentation. I do have prior experience as a technical writer, and I seek this opportunity to learn & grow.

Reach out to me on : mailguptaniharika@gmail.com

@KakoozaJerry

This comment has been minimized.

Copy link

@KakoozaJerry KakoozaJerry commented Apr 28, 2021

Hi,

I am Kakooza Abraham Jerry , interested in contributing to the Perl foundation as a technical writer.

You can find my resume on https://kakoozajerry.github.io/resume.html

My email is : abrahamkakooza@gmail.com

@charlesfreeborn

This comment has been minimized.

Copy link

@charlesfreeborn charlesfreeborn commented May 2, 2021

Hi team,

I am Charles Freeborn, technical writer with over 3 years, former editor for the freeCodeCamp publication, front-end web developer and currently learning iOS development.

I am excited about the Pearl project's proposal for GSoD 2021 and I'd like to give this a shot.

A couple questions though - there's no direction on how to apply and share your statement of interest.

Please advise on next steps on how to apply to be a technical writer for Perl's GSoD 2021.

Sharing links to my portfolio and writing samples here and my resume here.

@jmacdotorg

This comment has been minimized.

Copy link
Owner Author

@jmacdotorg jmacdotorg commented May 2, 2021

Hi everyone,

Thank you for your interest in this project. The Perl Foundation has selected its technical writer for Google Season of Docs 2021, and so this project no longer accepts applications. I invite you to apply to future projects involving Perl's documentation as they become available.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment