[Koha] Documentation - Are automated screenshots the way to go?

Fri Sep 8 09:20:25 NZST 2023

Hello dear community,

TLDR; We have a potential way of automating the screenshots of the 
manual that has interesting benefits. However, we are not sure if it 
would work with our screenshots. I would like to ask for your help 
analyzing the screenshots, to know if they are easy or difficult to 
automate. See 
https://docs.google.com/document/d/1wscmVmficQSpCmUDPNEYLp-TFJoR3gay2O6zS8q-Kak/edit?usp=sharing 
for how to analyze a screenshot. Read on for more information and a 
kitty at the bottom!

In the documentation team, we're looking at the possibility of 
automating the screenshot taking for the manual. If you've visited the 
manual before, you surely have stumbled upon screenshots of the 
interface that don't look anything like your interface. Our manual 
contains more than 1600 screenshots, with more being added with every 
new feature. This means that if there is a change in the interface, we 
must retake the screenshot. After the redesign of 22.11, all our 
screenshots were suddenly out of date. We are updating them little by 
little, but it is time consuming for the very small team of documenters 
that we are, so it is unimaginable to think that we can update all of 
them every version. We would rather spend our time documenting exciting 
new features than retaking screenshots simply because the interface 
looks different. And if you're thinking, "Well, we can live with 
screenshots from version 22.05 or even 20.11, it's not that bad!" take a 
look at this screenshot that is currently still in the latest manual as 
I write this 
https://koha-community.org/manual/latest/en/html/_images/fastadd.png (in 
the fast add cataloguing section 
https://koha-community.org/manual/latest/en/html/circulation.html#fast-add-cataloging 
; this section hasn't had any new features for a while so we never went 
over it to update it). Do you recognize it? :D

At Kohacon23, Jonathan Druart proposed a way to automate the screenshot 
taking using Cypress and Cypress Studio. Cypress is a tool mainly used 
by web developers for what is called end-to-end testing, where they 
write up a bunch of commands, input that into a browser and the browser 
will execute the commands as if it was a normal user. Cypress Studio is 
an extension of Cypress to be able to use Cypress without knowing how to 
write up the bunch of commands, i.e. for people like me who don't code. 
When using Cypress Studio, it records all the clicks and key presses 
that you do and converts it into code (that needs to be cleaned 
according to Jonathan). You can then feed that code into the browser and 
the browser will click where you clicked and type what you typed. (It 
does it super fast too, it's really cool to watch it go!)

For our purposes, anyone in the documentation team (or any motivated 
community member willing to help! *wink wink*) would take the screenshot 
using Cypress Studio. Then a developer would go in and clean the code 
generated by Cypress Studio. Then, every time we create a new manual (or 
whenever we want), we would run the Cypress scripts and all the 
screenshots would be automagically updated!

As well as having nice, up-to-date screenshots in our manual, this 
method has other advantages:
- It would allow us to have translated screenshots in the translated 
manuals.
- It would allow us to take the screenshot once and have it updated for 
every version with minimal additional work (admittedly it takes a lot 
more time to take the automated screenshot, but hopefully, this time 
would be saved in the future by not having to manually take the 
screenshot again).
- It would allow us to catch regressions in Koha (if something that 
should be there suddenly isn't there anymore, for example).

As the automation would be as time-consuming, if not more, than the 
manual way in the short-term, and would implicate developers as well as 
the documentation team, we would like to analyze the difficulty of 
automating before jumping in. Some screenshots are super easy to get to: 
you go into Cataloguing, click 'New record' and bam!, you're ready to 
take this screenshot 
https://koha-community.org/manual/latest/en/html/_images/catalogingform.png 
. Some screenshots need more preparation, like you need to turn on a 
system preference, then add a fine to a patron account, then try to 
check out an item to that patron and *now* you can take this screenshot 
https://koha-community.org/manual/latest/en/html/_images/patrondebt.png 
. If the majority of existing screenshots are hard or impossible to 
automate, it is not worth the trouble. However, if the majority of 
existing screenshots are easy, automation could be a way to save time in 
the long run. The thing is that we don't know how many are easy and how 
many are difficult.

This is where I would like to ask for your help. We would like to 
analyze the difficulty of about 10% of the images (around 100 to 150) in 
order to determine if the automation would be worth investing into. We 
currently have a Google spreadsheet with a list of about 1600 images. 
Anyone can go in and analyze an image. If several people analyze 2 or 3 
images each, we'll be done in no time!

It is not too difficult to analyze a screenshot, but you do need to know 
how to use Koha and know how to read HTML at least a little bit (just to 
spot the IDs or classes of the tags). I wrote up a procedure on how to 
do it in the Google drive 
https://docs.google.com/document/d/1wscmVmficQSpCmUDPNEYLp-TFJoR3gay2O6zS8q-Kak/edit?usp=sharing

After we determine if automation is the way to go, there are still a lot 
of things that would need to be ironed out before jumping in. Like what 
data to use, is the sample data enough? Do we only do the easy ones? 
When running the scripts, how do we determine that the screenshots have 
been correctly generated? Where do we store the Cypress scripts? When do 
we generate the screenshots? But all those questions will come later. 
First we must decide if we do it or not, and for that we need to analyze 
the images.

If you have opinions on this, or would like to help, or would simply 
like to know more about the Koha manual, there is an upcoming 
Documentation meeting on September 27, at 14 UTC. Everyone is welcome! 
(I swear we are very nice!) 
https://wiki.koha-community.org/wiki/Documentation_meeting_27_September_2023

Thank you for reading all the way to the bottom! :)

Caroline

As promised, here is the kitty! :)

⠀⠀⠀⠀⠀⠀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⣧⡑⢄⡀⠀⠀⠀⠀⠀⠀⢀⡴⣪⠁⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⣽⡨⠆⠉⠊⠉⠀⠈⠉⠐⠉⠮⣰⡇⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⢠⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢃⠀⠀⠀⠀
⠀⠀⠐⠠⠄⡀⡈⠀⠀⡰⠂⡄⠀⠀⠀⠀⡔⢢⡄⠀⠘⣀⡀⠤⠒
⠀⠀⠠⠤⠤⠤⡯⢥⡆⠑⠛⠁⢀⣻⣃⡀⠙⠛⠁⣶⢭⡧⠤⠤⠤
⠀⠀⢀⡠⠄⠒⠙⡅⠀⠀⠀⠀⠈⠉⠉⠀⠀⠀⠀⠀⡝⠁⠒⠠⠄
⠀⠀⠀⠀⠀⠀⠀⡨⠂⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢺⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⡰⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠱⡀⠀⠀⠀
⠀⠀⠀⠀⠀⢰⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢡⠀⠀⠀
⠀⠀⠀⠀⠀⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡆⠀⠀
⢀⠖⠐⢢⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀
⡆⠀⠀⠀⡄⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀
⢡⠀⠀⠀⡇⢡⠀⠀⠰⡄⠀⠀⠀⠀⡀⠀⠀⠀⡆⠀⠀⢠⠓⡀⠀
⠈⡄⠀⠀⠸⡀⠣⡀⠀⡇⠀⠀⠀⠀⡇⠀⠀⢠⠁⠀⡠⡇⠀⢡⠀
⠀⠈⢄⠀⠀⠑⢄⠈⠢⢴⡀⠀⢠⠀⡇⠀⠀⣌⠠⠚⣡⠃⠀⣸⠀
⠀⠀⠀⠳⣀⠀⠀⠑⠂⠤⢙⣛⡋⠉⢙⣣⣊⠀⠤⠊⠁⠀⡠⠃⠀
⠀⠀⠀⠀⠀⠑⠠⢀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠐⠁⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠒⠒⠂⠀⠀⠐⠒⠂⠉⠀⠀⠀⠀⠀⠀

Caroline Cyr-La-Rose, M.L.I.S. (she/her)
Librarian | Product Manager

1-833-INLIBRO (465-4276), ext. 221
caroline.cyr-la-rose at inlibro.com
https://www.inLibro.com