Create User Manual with screenshots and videos for Plone 6

[stevepiercy]

PLIP: Create User Manual with screenshots and videos for Plone 6

Responsible Persons

Proposer: Steve Piercy @stevepiercy

Seconder: Víctor Fernández de Alba @sneridagh

Abstract

The User Manual for Plone 6 does not exist, except for a small part of Volto in https://6.docs.plone.org/volto/user-manual/index.html.

We refer users to Plone 5 documentation Working with Content for Classic UI, but it is out of date.

Writing narrative text for a user manual is time consuming and rarely gets translated. If it gets translated, it is immediately out of date.

However through the use of Cypress as an automated test runner, we can take screenshots and videos of the frontends in any language, and incorporate these into a translated User Manual.

Motivation

User Manual documentation has been neglected in Plone 6 since its release. This shows how badly we disregard the end user.

Assumptions

Writing narrative documentation of a User Manual is intimidating and tedious. A picture or video is worth a thousand words, especially for those who don't write English as their first language.

The frontend rapidly changes, and we can update documentation automatically on every pull request.

Both Cypress and Playwright perform similar functions, but we already have all acceptance tests for Volto written with Cypress and a large base of developers with experience with Cypress. Supposedly Classic UI has opted to use Playwright, and there was some effort invested into this, but the author of this PLIP is not aware of the status of that effort.

A pull request was opened by @tkimnguyen plone/documentation#1547 during PloneConf 2023, but it used old screenshots, its content was not reviewed for accuracy, it is in a Draft state, and has stalled.

Proposal and Implementation

Use Cypress for recording videos and screenshots, and save them into the appropriate _static directory and repository.

Deliverables

• Automation of updated screenshots and videos on every merged pull request through GitHub Workflows.
• Port of Plone 5 user manual to Plone 6, converted to MyST with SEO headers and reviewed for accuracy.

Risks

None.

Participants

Steve Piercy, @stevepiercy