Google Season of Docs 2024 proposal
About Plone Foundation
Plone is an open-source content management system which has been actively developed since 2001.
The Plone Foundation is a 501(c)(3) non-profit charitable organization that protects and promotes Plone by furthering the development, marketing, and legal affairs of Plone and the Plone community.
Plone is used to create, edit, and manage digital content, like websites, intranets, and custom solutions. The result is a system trusted by governments, universities, businesses, and other organizations world-wide.
Plone comes with a flexible form builder that allows editors to create new forms via drag and drop, and define actions such as sending notifications and storing data for later use.
Plone includes faceted search that allows editors to create sophisticated search elements.
Plone is WCAG 2.0 compliant and meets or exceeds W3C’s WAI-AA and the US government's Section 508 standards for sight- and motor-impaired individuals.
Plone is available in over 30 languages, and can be easily extended for more languages.
Considering the diverse, global Plone community, we avoid cultural, gender, or other biases, thus creating inclusive and accessible documentation for the widest range of developers. Clear, consistent, and concise language also helps the many Plone developers for whom English is not their first language.
About the project
Plone 6 documentation lacks current end user manuals. Plone comes with a default React-based frontend called Volto and a legacy server-side template-based frontend called Classic UI. Most frontend development occurs in Volto, but documentation of its user interface has not been a priority for developers. The Classic UI interface was well documented for Plone 5, but needs to be updated for Plone 6. Additionally some features can only be performed in Classic UI, such as creating an event without an end date.
Only a small percentage of Plone contributors use English as their first language. Most Plone developers are skilled at writing code, not documentation in English. Localized end user documentation has been written in German, Brazilian Portuguese, and other languages by universities. Some of these Plone community members would be willing to share their work with a technical writer, pass it through a translation service, and use it as a basis for Plone 6 documentation.
With these end user manuals, automating screenshots and videos is greatly desired, as screenshots become outdated over time. Volto uses Jest for recording screenshots and videos during its continuous integration and testing. Classic UI uses robot.framework with Selenium and is migrating toward Playwright.
Plone 6 documentation of creating a project with Plone or contributing to Plone has reached a point where it is close to mature and stable. An experienced technical writer could approach these stories with fresh eyes, propose improvements with the Documentation Team, and work on agreed upon improvements.
Plone has participated in Google Summer of Code for many years. This combined with the Plone community's reputation as open and welcoming, we frequently get newcomers who are eager to contribute. However, they clearly lack the pre-requisite skills to contribute and lack knowledge of the Plone code base. We want to direct students and learners toward appropriate resources and away from GitHub until they have acquired the requisite skills to contribute. This in turn we hope will reduce triage efforts that drain time from our core contributors who would otherwise work on fixing bugs in and enhancing Plone.
Thus both end users, learners, and developers would benefit from documentation of getting started with Plone.
Scope
- Create and update end user documentation for the two Plone frontends, Volto and Classic UI.
- Automate screenshots and videos for inclusion in documentation.
- Document how to automate screenshots and videos for inclusion in documentation.
- Audit, propose, and update installation and contributing documentation.
- Present a talk about your work at an event, such as PloneConf 2024.
Measuring success
We track web statistics of our documentation website through Matomo. We will monitor new and updated pages and compare monthly and annual statistics with previous period for both returning and new visitors for a relative increase. We can also track users as they navigate through the site to the appropriate resource, whether it is for the end user, learner, developer, or contributor.
Only a few of our code repositories have statistically significant activity, with Volto being the most active. We would monitor the Volto repository for new contributors who create pull requests and the total number of pull requests over a given duration.
Plone 5.2 with its Classic UI frontend has 80 pages of user manual content underneath the section Working with Content. This content needs to be updated for Plone 6.0 with Classic UI as the secondary frontend.
Plone 6.0 with its default frontend of Volto has 4 pages in its User Manual.
Both frontend user manuals in Plone 6.0 should have a similar structure where practical. They should follow a how-to guide approach.
We would consider the project successful if, after publication of the new and updated documentation, a given number of measurement criteria in the following categories are met.
At least two website visitor measures:
- Periodic increases of new visitors of 10% from the previous term
- Periodic increases of new visitors of 10% compared to same period from the previous year
- Periodic increases of return visitors of 10% from the previous term
- Periodic increases of return visitors of 10% compared to same period from the previous year
At least one of the contributor measures:
- Decrease in unaccepted pull requests by newcomers by 10%.
- Increase in accepted pull requests by newcomers by 10%.
- Increase in total accepted pull requests by 10%.
All of the content measures:
- Automation of screenshot and video recording process is functional.
- How to automate screenshot and video recording is fully documented.
- All of the structure of both frontend user manuals exists.
- 35% of the content of both frontend user manuals exists
Timeline
We estimate that this work will take six months to complete.
We'll spend a month on-boarding the technical writer. Then we'll move onto automating screenshots and videos for the next month. We will spend the remaining months focusing on creating and updating the documentation.
| Dates | Action Items |
|---|---|
| May | On-boarding |
| June - August | Automation |
| September - October | Create and update documentation |
| November | Project completion |
Project budget
| Budget item | Amount | Running Total | Notes/justifications |
|---|---|---|---|
| Technical writer on-boarding, automation, update and create, test, and publish end user documentation for Plone | 12,500 | 12,500 | |
| Volunteer stipends | 500 | 2,500 | 5 volunteer stipends x 500 each |
| TOTAL | 15,000 |
Additional information
Plone has regular meetings of its various teams, including Documentation, Steering Circle, Plone Foundation Board, and teams centered around development of its packages.
We have an ample supply of newcomers to Plone, primarily through our Google Summer of Code participation. They will follow the new documentation, and we will encourage them to provide feedback to further improve it.
Our automated GitHub workflows create public previews of every pull request of documentation. They also test for valid syntax, links, spelling, and grammar. The Documentation Team reviews pull requests within a week, more often within a day.
Plone has participated in Google Season of Docs once before in 2019. The selected technical writer abandoned our project and did not respond to our attempts to contact them.
Steve Piercy (GitHub @stevepiercy) has been leading the Plone Documentation Team since 2022. Steve has been a contributor to Pylons Project documentation, including Pyramid and Deform, and has been using Sphinx for writing technical documentation since 2010. He uses MyST for new clients and open source projects, including Plone.
If we are not able to find a suitable candidate for the project, we have a strong technical writer in Steve Piercy as a secondary option. The Plone Documentation Team and Plone Foundation have committed to supporting the project. Additional content experts may review pull requests.
Plone participated in Google Summer of Code many times since 2006. Mentors coordinate regular meetings across distant time zones, and frequently communicate with the contributors and organizers to keep the project on track to succeed. We expect to continue these good habits throughout our participation in Google Season of Docs.