This talk is based on the six-month project completed under Season of Docs 2021. The aim was to identify the major problems in Perl’s existing documentation and to devise a strategy for its improvement. The project was completed successfully with a clear roadmap for the future.
Perl – an open-source, general-purpose programming language – has a lot of documentation, organized in the form of articles, FAQs, and web pages. Such detailed documentation, if not organized well, is overwhelming and frustrating for the audience. With over 100 core documentation pages, the users can easily get lost in the volume of the information, resulting in a bad user experience. This project aimed at resolving these issues and improving the structure of Perl’s core documentation. The project, divided into four major phases, was completed over the course of six months under the Google Season of Docs 2021.
- Content Audit It all began with a comprehensive content audit. Every single document in Perl’s core documentation was thoroughly analyzed to identify the shortcomings of the existing documentation and the areas for improvement. A content audit spreadsheet was created, recording the traits of individual documents including but not limited to the date when a document was updated, the intended audience, and cross-referencing. The audit served as a first step in improving the documentation.
- Gap Analysis The second phase was that of Gap Analysis, where insights from the Perl community came in handy. Individuals participated in informal user research and shared their feedback on the existing documentation. This gap analysis made the target audience a part of the project and provided clarification on the smaller, task-based, projects that could then be created to help improve the overall documentation.
- Information Architecture Content audit and gap analysis, followed by discussions with the contributors at Perl, identified the ways in which the documentation could be made more useful and usable. In order to give a structure to the documentation, it was essential to improve the existing information architecture (IA). A new IA was proposed, which then went through a series of revisions, to incorporate the needs of the users in the structure and presentation of Perl’s core documentation.
- Roadmap for the Future The final phase of the project was to devise a roadmap for the future of the documentation. This roadmap brought the findings of content audit, gap analysis, and information architecture together. Specific tasks and projects, along with possible limitations, were created and shared with the contributors of Perl to help improve the documentation in the days to come.
Quality documentation is imperative for the success of an engineering tool like a programming language. The existing documentation of Python, Prettier, and ESLint is a case in point. This project brought technical communication principles to documentation practices in the engineering discipline. The suggested improvements to Perl’s documentation will add value to the user experience by providing better navigation, ease of access, and a useful structure. The findings of this project highlight the best practices in engineering communication, serving as an example that documentation teams can follow in the future.
Perl’s Documentation: https://perldoc.pl/perl Google Season of Docs Proposal by Perl: https://gist.github.com/jmacdotorg/f306d9b0d4eae1dba879cad9cb8d2ace
