Continuing the discussion from Fundraising, open source, licensing:
I know there are and have been attempts to get this working with automation but I’m going ahead with what I can do now. Bird in the hand yada yada
What Paul and I have been working on. The audience for this is our user training at the conference in a bit over a week. Work in progress…
This is the ScribeHow version of the guide:
Update 2024-12-09: it was exported to markdown and added to the training docs repo and is now live
4 Likes
Works now. Had to make it public. Thanks for letting me know!
No prob.
Looks nice, but nothing about Listing Block (Collections)?
It’s in progress …
PR has been merged and the guide is now live!
2 Likes
Here are the remaining items to cover:
in addition to converting the remote S3 images so they’re local and adding alt text to them
A training for users/editors of Plone?
Plone is self explaining. The existing of a training would mean that an editor needs a training. Which is IMHO not necessary.
Please consider to fill one of the gaps in Plone documentation with (valuable) tipps for users/editors instead.
I don't agree here. Yes we need a user guide, how you call it, is not that important. For the time being, we lack of up to date user guides and not everything is self explaining, at least for non power users.
So i very welcome the initiative and the work with the auto generated screenshots. They could be used also for other user docs.
What is true though, we should not stop here and turn this one way or the other into a user guide, which is integrated in the docs it self.
This training is not this PLIP. I started work on automating the capture of videos and images in Recording videos and images for documentation by stevepiercy · Pull Request #1812 · plone/documentation · GitHub.
I think capturing an overview has value, but repetitive detail, not so much. How many times do you need to tell someone how to insert a different block and fiddle with its options? Whereas how to navigate to control panels; manage users, groups, and permissions; create forms; manage content from content types, and how to use other core features is helpful.
From the PLIP, it is trivial to switch to any supported language, then run the Cypress test suite to capture videos and images of the user interface in that language. Any text supporting the images can be translated with any translation service, including Firefox's translation support, which I find super useful when I travel. Altogether, it's a quick, easy, and cheap way to translate editor documentation. Maybe when we grow up big, we'll use Weblate for translations of this PLIP, and have more official translations than Django, which has 11 at the moment.
I dream big.
I'm glad to see both of these efforts to work on a user guide. I'd rather be in a situation where we have 2 and we can see which one works best, than a situation where we get bogged down discussing what to do and don't finish either one.
Steve, I'll review your PR and try to help give some pointers on what to do next -- but between catching up after the conference and getting ready for the holidays, it might take me a bit to get to it.
@polyester mentioned that he had something almost working, so maybe it could help for him and @stevepiercy to discuss (if they haven't already).
I just merged a PR to make all those screenshots local (not load from S3) and to add alt text
@ksuess one reason I've been (sporadically) hell bent on putting this out is that when I encounter a software package that has no or poor documentation, I think it must not be very professional and I give up trying to figure it out.
I too think the Volto UI is easy to use, but it hides some things so you have to, say, highlight text before you see a formatting tool, or you just generally have to click on things to discover functionality. That's fun for someone exploring who has time, but it's less fun for someone who doesn't yet know what they don't yet know.
1 Like