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
