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-r...@inlibro.com
https://www.inLibro.com
_______________________________________________
Koha mailing list http://koha-community.org
Koha@lists.katipo.co.nz
Unsubscribe: https://lists.katipo.co.nz/mailman/listinfo/koha
