Automated screenshots of Plone Classic user action sequences

Documentation
1

I'm trying out a script that takes screenshots of a sequence of user actions.

I'm trying the reset password sequence on https://classic.demo.plone.org/.

I created a user and set its password and email address.

But when I try to reset its password, I get this error.

What I did:

  • Clicked Log In
  • Clicked Get Help on the login form
  • Entered the username and clicked "Reset your password"

image
image1852×744 110 KB

2

I pointed instead at my local Plone site.

It generates HTML, Markdown, and PDF.

Code is at GitHub - tkimnguyen/plone_password_reset_capture: Generates screenshots of the password reset user action sequence · GitHub

3

I added code for the login sequence (ok, it's not a long one, but hey...). Common code moved to common.py.

4

Take a look at this https://heroshot.sh/ , it could even be used for other plone repos

5

See also an issue and PLIP that address this topic more broadly.

There's a couple of points of emphasis that members of the Write the Docs community have made since I created those items.

  • If your UI requires screenshots and videos to explain how to use it, it's probably a shitty UI. Use them sparingly, if it all. Narrative text is much preferable and easier to update.
  • Screenshots aren't translatable. Text is translatable.
  • Images, videos, and other large data files such as databases, MLMs, and AI data, should not be put into version control of a repository that is used primarily for development due to performance problems with git. Only references to media should be in such a repo. We've seen this in Volto, where media needlessly bloats its repo for developers. I learned this about 15 years ago while working on a media-heavy project for tree identification. Instead use something like git-lfs or DVC as an extension of git, and store your large data files in a compatible cloud storage.
1 Like
6

+100 - see python.org redesign.

7

OK, that's nice but a non sequitur. If you'd like to improve the UI, please have at it. I'm trying to document what we have and in a way that can be rerun automatically even if it changes (somewhat). Also, I'm sure all the folks who have contributed to the UI appreciate that kind of feedback...

8

I think you missed the point. Its corollary is "If your UI doesn't require screenshots and videos to use it, it's probably a great UI."

9

We've revived the automated screenshot generation for plone.app.mosaic last week. See the results here Getting started with Mosaic — Plone Mosaic 4.0.0 documentation

This is done by the existing playwright robottests and a github action, which deploys the rendered docs to the GH pages.

For previewing the docs in a PR, we generate artifacts which we can inspect if needed.

:fish:

1 Like
10

That's a much nicer way to put it :slight_smile:

Any thoughts about the way I'm going at it?

11

Unsustainable, because it's not directly tied to the repository code base. If the underlying source code changes, your script is obsolete.

@petschki implements a more sustainable model that's directly tied to tests on the source code, which I've previously suggested in the PLIP and original documentation issue. However, see the points I made in my earlier comment.

I don't know what's the plan for Mosaic documentation.

12

Well, the plan was, that the old setup of mosaic documentation is working again. Since we're having a mosaic example page on classic.demo.plone.org since last week it might make sense to integrate it into docs.plone.org also ... but we can discuss that in our blicca (classic) meeting next week @stevepiercy if you like.