Screenshots internationalization for the manual (and acceptance tests?)
Hello everybody, I have spent (too much) time trying to automatically generate the screenshots of the manual. The idea behind that was multiple: keep the screenshots up-to-date from one version of Koha to the others, and generate screenshots in each language of the manual. I was really excited after the first half hour when I successfully took my first screenshot with only few lines of code. But after a couple of days I realize that the task is very huge: we have more than 1300 images in the manual, and I have generated only 68 so far. First I need to know how important is that for you. Will it really change our lives to have screenshots translated in other languages (and kept in sync with the interface)? How important is the value added? One thing is sure: if someone wants to translate screenshots, they should do it in a generic way so all languages can take advantage of it. The hidden added value of such mechanism is to add a huge test coverage: we are going to make sure the screenshots can be generated in several languages, catching issues we do not cover in our test suites, etc. A bit of technique: the screenshots are taken using Selenium tests (which we already use a bit in the test suites): it simulates a user's interaction with the interface. The big problem is that, for now, only developers could help me. But do not stop reading now please :) The code looks like that: C4::Context->set_preference('SpecifyReturnDate', 1); $driver->get($base_url.'circ/returns.pl'); screenshot("SpecifyReturnDate", { class => "yui-u first" }); For the "SpecifyReturnDate" screenshot, we set the syspref to 1, hit returns.pl and create a screenshot from the element with a class "yui-u first" (yes the element should have an id). As you can imagine this one is part of the easiest ones. Now imagine "FineNotifyAtCheckin", we want to capture the alert box when the patron has fines and returns an item. The code is: C4::Context->set_preference('FineNotifyAtCheckin', 1); my $b = Koha::Items->find(74)->barcode; issue( $patron, $b ); Koha::Account::Line->new({ borrowernumber => $patron->borrowernumber, accountno => 1, amountoutstanding => 5 })->store; checkin( $b ); screenshot("FineNotifyAtCheckin", { class => "dialog alert" } ); Koha::Account::Lines->search({ borrowernumber => $patron->borrowernumber })->delete; First I assume I have an item with itemnumber=74 that can be issued by a given patron. I check it out and create a fine of 5. I check the item in and tadaaa I can take the screenshot for the alert dialog. Then I clean up. And trust me, this is not the hardest. So what I suggest is that, if (and only if) people are very interested in contributing to translate the screenshots and in the concept of having the whole interface tested, we could offer an easy way to contribute to this project. We could do that using Cucumber (see also bug 13849), and let people write something much more readable (by anybody), like: Scenario: Take a screenshot for SpecifyReturnDate Given I have set the syspref SpecifyReturnDate to 1 And I hit the circ/returns.pl Then I take a screenshot of the element with the class "yui-u first" Or: Scenario: Take a screenshot for FineNotifyAtCheckin Given I have set the syspref FineNotifyAtCheckin to 1 And I checked an item out to a patron And I added a fine of 5 to the patron And I checked the item in Then I take a screenshot of the element with the class "dialog alert" Does it seem more readable? Let me know what do you think of that and if you are willing to help. Then I will see if I can dedicate more time to this project. Cheers, Jonathan Additional information: - For now only sample data from "en" are used. Part of the interface is not translated yet (item types, authorised values, framework, etc.) - The process does not finish for "fr" because of bug 20043 - I have already found several bugs (not reported yet) writing these tests. - The screenshots I generated are from the installer (all of them) and the administration part (~50%) - Currently I cannot regenerate only 1 screenshot (if something went wrong for instance). They should be independent (unless for the installer part) and the script should take an image name in parameter (like perl generate_screenshot.pl --name FineNotifyAtCheckin --lang es). - Could be done later: * Generate screenshots for "fr" with UNIMARC data * Use sample data from the language we want * Have separate data set depending on the language (like having the biblio titles or patron names depending on the region: John Doe for 'en', Jean Dupont for 'fr', Juan Pérez for 'es', etc.) * And certainly much more... The links to what have been done so far: (manual with only the installer and administration sections, these links are temporary) ar - http://download.koha-community.org/manual/wip_screenshots/ar/html/ en - http://download.koha-community.org/manual/wip_screenshots/en/html/ es - http://download.koha-community.org/manual/wip_screenshots/es/html/ it - http://download.koha-community.org/manual/wip_screenshots/it/html/ pt_BR - http://download.koha-community.org/manual/wip_screenshots/pt_BR/html/ zh_TW - http://download.koha-community.org/manual/wip_screenshots/zh_TW/html/ Here is the list of the images that have been generated: https://pastebin.com/RQV35cu2
Good morning all ! For me, having the screenshots in the correct language is quite important. However, having the screenshots updated every release is not necessary. For example, I don't mind if there is a slight difference in the screenshot when that difference is not related to the explained feature. Don't get me wrong, I love the idea of automating the screenshots and the possibilities it offers, but I believe that a lot of them will need to be edited afterward in order to be cropped, added overlay, and so on, which make the automation less appealing. I also think that it will be a nightmare to maintain in the long run and making the documentation process even harder. The option is to generate the screenshots when we can. Its a long process at first, but any body are able to take a screenshot, without having to code anything, which is, in my opinion, a big advantage. My 164 Satochis ($0.02) on this sunday morning :) Eric On 2018-01-19 11:29, Jonathan Druart wrote:
Hello everybody,
I have spent (too much) time trying to automatically generate the screenshots of the manual. The idea behind that was multiple: keep the screenshots up-to-date from one version of Koha to the others, and generate screenshots in each language of the manual. I was really excited after the first half hour when I successfully took my first screenshot with only few lines of code. But after a couple of days I realize that the task is very huge: we have more than 1300 images in the manual, and I have generated only 68 so far.
First I need to know how important is that for you. Will it really change our lives to have screenshots translated in other languages (and kept in sync with the interface)? How important is the value added? One thing is sure: if someone wants to translate screenshots, they should do it in a generic way so all languages can take advantage of it.
The hidden added value of such mechanism is to add a huge test coverage: we are going to make sure the screenshots can be generated in several languages, catching issues we do not cover in our test suites, etc. A bit of technique: the screenshots are taken using Selenium tests (which we already use a bit in the test suites): it simulates a user's interaction with the interface.
The big problem is that, for now, only developers could help me. But do not stop reading now please :)
The code looks like that: C4::Context->set_preference('SpecifyReturnDate', 1); $driver->get($base_url.'circ/returns.pl'); screenshot("SpecifyReturnDate", { class => "yui-u first" }); For the "SpecifyReturnDate" screenshot, we set the syspref to 1, hit returns.pl and create a screenshot from the element with a class "yui-u first" (yes the element should have an id). As you can imagine this one is part of the easiest ones.
Now imagine "FineNotifyAtCheckin", we want to capture the alert box when the patron has fines and returns an item. The code is: C4::Context->set_preference('FineNotifyAtCheckin', 1); my $b = Koha::Items->find(74)->barcode; issue( $patron, $b ); Koha::Account::Line->new({ borrowernumber => $patron->borrowernumber, accountno => 1, amountoutstanding => 5 })->store; checkin( $b ); screenshot("FineNotifyAtCheckin", { class => "dialog alert" } ); Koha::Account::Lines->search({ borrowernumber => $patron->borrowernumber })->delete; First I assume I have an item with itemnumber=74 that can be issued by a given patron. I check it out and create a fine of 5. I check the item in and tadaaa I can take the screenshot for the alert dialog. Then I clean up.
And trust me, this is not the hardest.
So what I suggest is that, if (and only if) people are very interested in contributing to translate the screenshots and in the concept of having the whole interface tested, we could offer an easy way to contribute to this project.
We could do that using Cucumber (see also bug 13849), and let people write something much more readable (by anybody), like: Scenario: Take a screenshot for SpecifyReturnDate Given I have set the syspref SpecifyReturnDate to 1 And I hit the circ/returns.pl Then I take a screenshot of the element with the class "yui-u first"
Or: Scenario: Take a screenshot for FineNotifyAtCheckin Given I have set the syspref FineNotifyAtCheckin to 1 And I checked an item out to a patron And I added a fine of 5 to the patron And I checked the item in Then I take a screenshot of the element with the class "dialog alert"
Does it seem more readable?
Let me know what do you think of that and if you are willing to help. Then I will see if I can dedicate more time to this project.
Cheers, Jonathan
Additional information: - For now only sample data from "en" are used. Part of the interface is not translated yet (item types, authorised values, framework, etc.) - The process does not finish for "fr" because of bug 20043 - I have already found several bugs (not reported yet) writing these tests. - The screenshots I generated are from the installer (all of them) and the administration part (~50%) - Currently I cannot regenerate only 1 screenshot (if something went wrong for instance). They should be independent (unless for the installer part) and the script should take an image name in parameter (like perl generate_screenshot.pl --name FineNotifyAtCheckin --lang es). - Could be done later: * Generate screenshots for "fr" with UNIMARC data * Use sample data from the language we want * Have separate data set depending on the language (like having the biblio titles or patron names depending on the region: John Doe for 'en', Jean Dupont for 'fr', Juan Pérez for 'es', etc.) * And certainly much more... The links to what have been done so far: (manual with only the installer and administration sections, these links are temporary) ar - http://download.koha-community.org/manual/wip_screenshots/ar/html/ en - http://download.koha-community.org/manual/wip_screenshots/en/html/ es - http://download.koha-community.org/manual/wip_screenshots/es/html/ it - http://download.koha-community.org/manual/wip_screenshots/it/html/ pt_BR - http://download.koha-community.org/manual/wip_screenshots/pt_BR/html/ zh_TW - http://download.koha-community.org/manual/wip_screenshots/zh_TW/html/
Here is the list of the images that have been generated: https://pastebin.com/RQV35cu2 _______________________________________________ Koha mailing list http://koha-community.org Koha@lists.katipo.co.nz https://lists.katipo.co.nz/mailman/listinfo/koha
-- Eric Bégin Tél. : 888 604-2627 Cell. : 514 777-6572 Eric.Begin@inLibro.com <mailto:Eric.Begin@inLibro.com> inLibro | Spécialistes en technologies documentaires | www.inLibro.com <http://www.inLibro.com>
Hi Éric, The screenshot are automatically cropped, did you watch at the examples I generated? For each screenshots it retrieves the positions of a list of elements, so no need to maintain or keep them up-to-date, we just need to keep the same elements on the pages (id or class). It is the same problem of any selenium scripts. As I said, if you generate 1 screenshot in a generic way, it will be kept up-to-date and for all languages. If you generate it manually, it will not. I am sure it is less time consuming to write the 5 lines of code than take and crop a screenshot for the 9 languages we generate the manual. Cheers, Jonathan On Sun, 21 Jan 2018 at 10:37 Eric Bégin <eric.begin@inlibro.com> wrote:
Good morning all !
For me, having the screenshots in the correct language is quite important.
However, having the screenshots updated every release is not necessary. For example, I don't mind if there is a slight difference in the screenshot when that difference is not related to the explained feature.
Don't get me wrong, I love the idea of automating the screenshots and the possibilities it offers, but I believe that a lot of them will need to be edited afterward in order to be cropped, added overlay, and so on, which make the automation less appealing. I also think that it will be a nightmare to maintain in the long run and making the documentation process even harder.
The option is to generate the screenshots when we can. Its a long process at first, but any body are able to take a screenshot, without having to code anything, which is, in my opinion, a big advantage.
My 164 Satochis ($0.02) on this sunday morning :)
Eric
Hello everybody,
I have spent (too much) time trying to automatically generate the screenshots of the manual. The idea behind that was multiple: keep the screenshots up-to-date from one version of Koha to the others, and generate screenshots in each language of the manual. I was really excited after the first half hour when I successfully took my first screenshot with only few lines of code. But after a couple of days I realize that the task is very huge: we have more than 1300 images in the manual, and I have generated only 68 so far.
First I need to know how important is that for you. Will it really change our lives to have screenshots translated in other languages (and kept in sync with the interface)? How important is the value added? One thing is sure: if someone wants to translate screenshots, they should do it in a generic way so all languages can take advantage of it.
The hidden added value of such mechanism is to add a huge test coverage: we are going to make sure the screenshots can be generated in several languages, catching issues we do not cover in our test suites, etc. A bit of technique: the screenshots are taken using Selenium tests (which we already use a bit in the test suites): it simulates a user's interaction with the interface.
The big problem is that, for now, only developers could help me. But do not stop reading now please :)
The code looks like that: C4::Context->set_preference('SpecifyReturnDate', 1); $driver->get($base_url.'circ/returns.pl'); screenshot("SpecifyReturnDate", { class => "yui-u first" }); For the "SpecifyReturnDate" screenshot, we set the syspref to 1, hit returns.pl and create a screenshot from the element with a class "yui-u first" (yes the element should have an id). As you can imagine this one is part of the easiest ones.
Now imagine "FineNotifyAtCheckin", we want to capture the alert box when the patron has fines and returns an item. The code is: C4::Context->set_preference('FineNotifyAtCheckin', 1); my $b = Koha::Items->find(74)->barcode; issue( $patron, $b ); Koha::Account::Line->new({ borrowernumber => $patron->borrowernumber, accountno => 1, amountoutstanding => 5 })->store; checkin( $b ); screenshot("FineNotifyAtCheckin", { class => "dialog alert" } ); Koha::Account::Lines->search({ borrowernumber => $patron->borrowernumber })->delete; First I assume I have an item with itemnumber=74 that can be issued by a given patron. I check it out and create a fine of 5. I check the item in and tadaaa I can take the screenshot for the alert dialog. Then I clean up.
And trust me, this is not the hardest.
So what I suggest is that, if (and only if) people are very interested in contributing to translate the screenshots and in the concept of having
whole interface tested, we could offer an easy way to contribute to this project.
We could do that using Cucumber (see also bug 13849), and let people write something much more readable (by anybody), like: Scenario: Take a screenshot for SpecifyReturnDate Given I have set the syspref SpecifyReturnDate to 1 And I hit the circ/returns.pl Then I take a screenshot of the element with the class "yui-u first"
Or: Scenario: Take a screenshot for FineNotifyAtCheckin Given I have set the syspref FineNotifyAtCheckin to 1 And I checked an item out to a patron And I added a fine of 5 to the patron And I checked the item in Then I take a screenshot of the element with the class "dialog alert"
Does it seem more readable?
Let me know what do you think of that and if you are willing to help. Then I will see if I can dedicate more time to this project.
Cheers, Jonathan
Additional information: - For now only sample data from "en" are used. Part of the interface is not translated yet (item types, authorised values, framework, etc.) - The process does not finish for "fr" because of bug 20043 - I have already found several bugs (not reported yet) writing these tests. - The screenshots I generated are from the installer (all of them) and
On 2018-01-19 11:29, Jonathan Druart wrote: the the
administration part (~50%) - Currently I cannot regenerate only 1 screenshot (if something went wrong for instance). They should be independent (unless for the installer part) and the script should take an image name in parameter (like perl generate_screenshot.pl --name FineNotifyAtCheckin --lang es). - Could be done later: * Generate screenshots for "fr" with UNIMARC data * Use sample data from the language we want * Have separate data set depending on the language (like having the biblio titles or patron names depending on the region: John Doe for 'en', Jean Dupont for 'fr', Juan Pérez for 'es', etc.) * And certainly much more... The links to what have been done so far: (manual with only the installer and administration sections, these links are temporary) ar - http://download.koha-community.org/manual/wip_screenshots/ar/html/ en - http://download.koha-community.org/manual/wip_screenshots/en/html/ es - http://download.koha-community.org/manual/wip_screenshots/es/html/ it - http://download.koha-community.org/manual/wip_screenshots/it/html/ pt_BR - http://download.koha-community.org/manual/wip_screenshots/pt_BR/html/ zh_TW - http://download.koha-community.org/manual/wip_screenshots/zh_TW/html/
Here is the list of the images that have been generated: https://pastebin.com/RQV35cu2 _______________________________________________ Koha mailing list http://koha-community.org Koha@lists.katipo.co.nz https://lists.katipo.co.nz/mailman/listinfo/koha
-- Eric Bégin
Tél. : 888 604-2627 Cell. : 514 777-6572 Eric.Begin@inLibro.com <mailto:Eric.Begin@inLibro.com>
inLibro | Spécialistes en technologies documentaires | www.inLibro.com <http://www.inLibro.com> _______________________________________________ Koha mailing list http://koha-community.org Koha@lists.katipo.co.nz https://lists.katipo.co.nz/mailman/listinfo/koha
Hi Jonathan, I'm not sure I understand everything in your email. Let me know if I'm understanding this right. What you are asking is if we (the non-technical ppl) would be willing to write up "steps" for each of the 1300+ screenshots in the manual so that developers can translate those into code to automate the screenshot-taking and deploy it across all manuals and all languages. Do we have enough developers in the community to do that? I don't want to speak for the whole documentation team, but I think that if we do it little by little (when we review a section or sub-section for example), it is feasible. It might take a couple of years to go through the 1300+ pictures, though. And we would need to have a way to know which screenshot has been automated and which is still manual (ideally, directly in the manual, maybe with a comment?). When we want to add a screenshot, let's say for a new feature, how does the workflow go? Do we take a manual screenshot first and write up the steps? Or just write the steps and wait for the developer to take the screenshot? What about when we want to add squares or circles to point out a specific button (do we do that in the manual?) or add numbers like in this example you sent : http://download.koha-community.org/manual/wip_screenshots/en/html/_images/ma... ? I hope this helps your reflection Caroline Cyr La Rose, M.L.I.S. Head of training and support, inLibro
Hi Caroline, I am suggesting to write a (BDD) syntax to help everybody to write these steps. You would be able to generate the screenshots and test locally if the steps are correct. The syntax would look like the two examples I gave, like: Scenario: Take a screenshot for FineNotifyAtCheckin Given I have set the syspref FineNotifyAtCheckin to 1 And I checked an item out to a patron And I added a fine of 5 to the patron And I checked the item in Then I take a screenshot of the element with the class "dialog alert" You will not need the help of a developer to know if it does what you expected. Of course I know it is a big job to generate such steps for every screenshot, but I think it is the way to go to get up-to-date (and translated) screenshots in the long term. I have already did the job for the image "marc21_basic_setup.png" (see the links at the bottom of my original email) and there are no numbers or circles. It cannot be automated. Thanks for your answer. Jonathan On Mon, 26 Feb 2018 at 13:44 Caroline Cyr-La-Rose < caroline.cyr-la-rose@inlibro.com> wrote:
Hi Jonathan,
I'm not sure I understand everything in your email. Let me know if I'm understanding this right. What you are asking is if we (the non-technical ppl) would be willing to write up "steps" for each of the 1300+ screenshots in the manual so that developers can translate those into code to automate the screenshot-taking and deploy it across all manuals and all languages.
Do we have enough developers in the community to do that? I don't want to speak for the whole documentation team, but I think that if we do it little by little (when we review a section or sub-section for example), it is feasible. It might take a couple of years to go through the 1300+ pictures, though. And we would need to have a way to know which screenshot has been automated and which is still manual (ideally, directly in the manual, maybe with a comment?).
When we want to add a screenshot, let's say for a new feature, how does the workflow go? Do we take a manual screenshot first and write up the steps? Or just write the steps and wait for the developer to take the screenshot?
What about when we want to add squares or circles to point out a specific button (do we do that in the manual?) or add numbers like in this example you sent :
http://download.koha-community.org/manual/wip_screenshots/en/html/_images/ma... ?
I hope this helps your reflection
Caroline Cyr La Rose, M.L.I.S. Head of training and support, inLibro
_______________________________________________ Koha mailing list http://koha-community.org Koha@lists.katipo.co.nz https://lists.katipo.co.nz/mailman/listinfo/koha
participants (3)
-
Caroline Cyr-La-Rose -
Eric Bégin -
Jonathan Druart