Documentation is a tricky thing for open-source programming languages. The process of managing and updating the documents requires a lot of time, effort, and dedication. The overall documentation doesn’t only have to be updated regularly, but it also needs to be presented and organized in a way that the users can find what they are looking for without any hassle. This job becomes more demanding when the learning aspect of documentation is of prime importance.

Perl, being an open-source, general-purpose programming language, had all these concerns. The documentation of Perl consists of hundreds of individual articles (which are all extremely useful for existing as well as new users). However, the sheer volume of these documents can be confusing, especially for people who are new to Perl. To take care of these concerns, Perl proposed a project for Google Season of Docs (GSoD) 2021.

I got a chance to work on this project as a technical writer. The project was spread over a period of six months, resulting in a workable plan for the future of Perl’s documentation.

The Four (Plus One) Phases

The primary aim of the project was to conduct a comprehensive content audit, followed by a gap analysis. These analyses helped in identifying the major shortcomings of Perl’s documentation. The valuable information obtained from these analyses was then combined with user feedback and discussions with Perl’s docs team to formulate a plan for the future.

The major phases of the project included the following.

Phase 1: Content Audit

The first step toward the improvement of the documentation was to conduct a comprehensive audit of the existing documentation. This not only helped in developing an understanding of the documentation but also highlighted the areas of improvement.

Phase 2: Gap Analysis

Gap analysis came next, where existing and potential users of Perl gave feedback about the documentation. This helped in incorporating the input of users in the project and understanding their pain points.

Phase 2.75: Actions for Gaps

Phase two and three-quarters, originally not included in the proposal, were introduced to organize the findings of the content audit and gap analyses. An action plan with task-based projects was created that turned out to be extremely helpful in the end.

Phase 3: Information Architecture

Once the users gave their feedback and pretty much all the areas for improvement were highlighted, a new structure for Perl’s documentation was proposed. The primary goal here was to reorganize the existing documentation so that the users find it easy to interact with and do not get overwhelmed or frustrated when seeking help from the documentation.

Phase 4: Roadmap for the Future

The concluding phase of the project was where everything was brought together. From the content audit to the information architecture, every finding served as a significant step to improve Perl’s documentation. A roadmap was then created for the future, where each area of concern was given due attention. The tasks and projects in this roadmap will be taken up one by one, adding great value to the existing documentation of Perl.

Accomplishments

The project succeeded in meeting its goals and was included in the list of successful projects released by Google. The findings of this project will serve as a huge step in the future of Perl’s documentation. This project helped in:

• Identifying key issues in the existing documentation concerning various aspects such as usability, navigation, readability, and coherence.
• Highlighting the shortcomings of the organization of documentation and the impacts on users’ interaction with the content.
• Reorganizing the content in an effective manner so as to give the entire documentation a more logical structure.
• Developing a roadmap for the future that can be followed to improve Perl’s documentation in the days to come.

GSoD is an excellent resource for open-source organizations and technical writers. On the one hand, open-sources organizations can get help with their documentation in a dedicated manner. On the other, technical writers get more experience and exposure. Working in open-source environments is an excellent opportunity, one that freelance technical writers can hugely benefit from.

About Perl

Perl is a free, open-source, general-purpose programming language originally developed by Larry Wall in the 1980s. 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.

Acknowledgments

This project would not have been successful without the help and support of the following people.

• Jason McIntosh, my mentor and project lead, for always being there to answer my questions and making sure everything was on track.
• Dan Book, Makoto Nozaki, and other members of the Perl community for their feedback and help throughout the project.
• Arthur Berger, President STC Carolina Chapter, for mentoring and helping me in creating a proposal.
• Four volunteers (Anindita Basu, Fareha Nousheen, Huda Mahmood, and Najeeb Afzal) for providing their valuable feedback about the existing documentation of Perl.

And thanks to Google for such an incredible initiative. This project has taught me a lot, and I’m sure I’ll be benefiting from this learning for a long time.

Reference Documents

• Perl’s Documentation
• Perl’s Proposal: Submitted to Google Season of Docs 2021
• Final Project Report: Audit and Gap Analysis of Perl’s Documentation