You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Jan Høydahl <ja...@cominvent.com> on 2018/08/02 10:37:12 UTC
Keeping RefGuide screenshots up to date
In SOLR-12613 we'll rename the "Cloud" menu in Admin UI to "Cluster". This affects pretty much
all admin UI screenshots in the Reference Guide, so the next question then is "How do we
keep all those screenshots up to date?". I counted a total of 42 screen shots of the UI, many
which require creating collections, adding data, typing things into the UI etc up front.
Due to the work involved, we often tend to update only a few shots and leave others as-is even
if they are inaccurate. Example is the new "Suggestions" menu tab - there are 27 screen
shots in the ref guide which are not updated with that menu option.
For SOLR-12613 I'm tempted to only update the four images in "cloud-screens" folder for now.
Perhaps for the future an automated approach can be taken using Selenium, as outlined in
this post: https://blog.codeship.com/automating-screenshots-in-documentation/ This could
in first phase be a standalone tool to generate screenshots but could also be extended with
other tests to get some validation of the UI itself, which is completely lacking today. WDYT?
--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Keeping RefGuide screenshots up to date
Posted by Alexandre Rafalovitch <ar...@gmail.com>.
That sounds good.
And, from a quick look, the Asciidoc screenshot tool uses Geb, which
uses Selenium as well (WebDriver anyway). So, maybe there is a clear
path somewhere in there.
Regards,
Alex.
On 2 August 2018 at 19:01, Jan Høydahl <ja...@cominvent.com> wrote:
> Neither though I think will get a collection into the correct pre-populated
> state
>
>
> We already have JUnit, so we could write a new test suite for UI testing,
> perhaps
> one that is not run by default, but has its own ant targer? Using JUnit we
> can
> pre-populate Solr clusters. The SolrUITestBase class could have conveience
> methods to create collections, feed example docs etc.
>
> Then, using Selenium webdriver as part of a JUnit test, we can navigate to
> the
> exact location in the UI we need, asserting various things along the way,
> and
> finally we can do screenshots of the whole page or limited to a CSS
> selector.
> See http://www.baeldung.com/java-selenium-with-junit-and-testng
>
> --
> Jan Høydahl, search solution architect
> Cominvent AS - www.cominvent.com
>
> 2. aug. 2018 kl. 16:15 skrev Alexandre Rafalovitch <ar...@gmail.com>:
>
> +1 as I think it would open up other example/documentation options.
>
> Chrome driver by itself may be sufficient for just sample screenshots,
> but Selenium may be better for testing and more advanced use-cases.
> Neither though I think will get a collection into the correct
> pre-populated state. So that would still need to be figured out (maybe
> something like Postman: https://www.getpostman.com/postman ).
>
> I think it would also go hand-in-hand with improving examples, so the
> screenshots are taken of something users could also use/reproduce.
> And/or with longer "getting started" example that could be automated
> with screenshots along the way.
>
> Regards,
> Alex.
>
> On 2 August 2018 at 06:37, Jan Høydahl <ja...@cominvent.com> wrote:
>
> In SOLR-12613 we'll rename the "Cloud" menu in Admin UI to "Cluster". This
> affects pretty much
> all admin UI screenshots in the Reference Guide, so the next question then
> is "How do we
> keep all those screenshots up to date?". I counted a total of 42 screen
> shots of the UI, many
> which require creating collections, adding data, typing things into the UI
> etc up front.
>
> Due to the work involved, we often tend to update only a few shots and leave
> others as-is even
> if they are inaccurate. Example is the new "Suggestions" menu tab - there
> are 27 screen
> shots in the ref guide which are not updated with that menu option.
>
> For SOLR-12613 I'm tempted to only update the four images in "cloud-screens"
> folder for now.
>
> Perhaps for the future an automated approach can be taken using Selenium, as
> outlined in
> this post:
> https://blog.codeship.com/automating-screenshots-in-documentation/ This
> could
> in first phase be a standalone tool to generate screenshots but could also
> be extended with
> other tests to get some validation of the UI itself, which is completely
> lacking today. WDYT?
>
> --
> Jan Høydahl, search solution architect
> Cominvent AS - www.cominvent.com
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Keeping RefGuide screenshots up to date
Posted by Jan Høydahl <ja...@cominvent.com>.
> Neither though I think will get a collection into the correct pre-populated state
We already have JUnit, so we could write a new test suite for UI testing, perhaps
one that is not run by default, but has its own ant targer? Using JUnit we can
pre-populate Solr clusters. The SolrUITestBase class could have conveience
methods to create collections, feed example docs etc.
Then, using Selenium webdriver as part of a JUnit test, we can navigate to the
exact location in the UI we need, asserting various things along the way, and
finally we can do screenshots of the whole page or limited to a CSS selector.
See http://www.baeldung.com/java-selenium-with-junit-and-testng <http://www.baeldung.com/java-selenium-with-junit-and-testng>
--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com
> 2. aug. 2018 kl. 16:15 skrev Alexandre Rafalovitch <ar...@gmail.com>:
>
> +1 as I think it would open up other example/documentation options.
>
> Chrome driver by itself may be sufficient for just sample screenshots,
> but Selenium may be better for testing and more advanced use-cases.
> Neither though I think will get a collection into the correct
> pre-populated state. So that would still need to be figured out (maybe
> something like Postman: https://www.getpostman.com/postman ).
>
> I think it would also go hand-in-hand with improving examples, so the
> screenshots are taken of something users could also use/reproduce.
> And/or with longer "getting started" example that could be automated
> with screenshots along the way.
>
> Regards,
> Alex.
>
> On 2 August 2018 at 06:37, Jan Høydahl <ja...@cominvent.com> wrote:
>> In SOLR-12613 we'll rename the "Cloud" menu in Admin UI to "Cluster". This affects pretty much
>> all admin UI screenshots in the Reference Guide, so the next question then is "How do we
>> keep all those screenshots up to date?". I counted a total of 42 screen shots of the UI, many
>> which require creating collections, adding data, typing things into the UI etc up front.
>>
>> Due to the work involved, we often tend to update only a few shots and leave others as-is even
>> if they are inaccurate. Example is the new "Suggestions" menu tab - there are 27 screen
>> shots in the ref guide which are not updated with that menu option.
>>
>> For SOLR-12613 I'm tempted to only update the four images in "cloud-screens" folder for now.
>>
>> Perhaps for the future an automated approach can be taken using Selenium, as outlined in
>> this post: https://blog.codeship.com/automating-screenshots-in-documentation/ This could
>> in first phase be a standalone tool to generate screenshots but could also be extended with
>> other tests to get some validation of the UI itself, which is completely lacking today. WDYT?
>>
>> --
>> Jan Høydahl, search solution architect
>> Cominvent AS - www.cominvent.com
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
Re: Keeping RefGuide screenshots up to date
Posted by Alexandre Rafalovitch <ar...@gmail.com>.
+1 as I think it would open up other example/documentation options.
Chrome driver by itself may be sufficient for just sample screenshots,
but Selenium may be better for testing and more advanced use-cases.
Neither though I think will get a collection into the correct
pre-populated state. So that would still need to be figured out (maybe
something like Postman: https://www.getpostman.com/postman ).
I think it would also go hand-in-hand with improving examples, so the
screenshots are taken of something users could also use/reproduce.
And/or with longer "getting started" example that could be automated
with screenshots along the way.
Regards,
Alex.
On 2 August 2018 at 06:37, Jan Høydahl <ja...@cominvent.com> wrote:
> In SOLR-12613 we'll rename the "Cloud" menu in Admin UI to "Cluster". This affects pretty much
> all admin UI screenshots in the Reference Guide, so the next question then is "How do we
> keep all those screenshots up to date?". I counted a total of 42 screen shots of the UI, many
> which require creating collections, adding data, typing things into the UI etc up front.
>
> Due to the work involved, we often tend to update only a few shots and leave others as-is even
> if they are inaccurate. Example is the new "Suggestions" menu tab - there are 27 screen
> shots in the ref guide which are not updated with that menu option.
>
> For SOLR-12613 I'm tempted to only update the four images in "cloud-screens" folder for now.
>
> Perhaps for the future an automated approach can be taken using Selenium, as outlined in
> this post: https://blog.codeship.com/automating-screenshots-in-documentation/ This could
> in first phase be a standalone tool to generate screenshots but could also be extended with
> other tests to get some validation of the UI itself, which is completely lacking today. WDYT?
>
> --
> Jan Høydahl, search solution architect
> Cominvent AS - www.cominvent.com
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Keeping RefGuide screenshots up to date
Posted by Shawn Heisey <ap...@elyograg.org>.
On 8/2/2018 8:16 AM, Cassandra Targett wrote:
> My feeling is we should update all of them, especially if the change
> you're talking about isn't made until 8 - a major version feels like a
> good time to refresh all the screenshots as there have been enough
> smaller CSS changes in 7.x that make them obsolete in many other ways.
+1 to update all screenshots in the 8.0 reference guide.
That way we can be absolutely sure that what a user sees in the
documentation will not be different than what they see on their own
screen. This is a very fast-moving project, so it is easy for info in
the docs to get out of date.
Here's an interesting extension:
https://chrome.google.com/webstore/detail/full-page-screen-capture/fdpohaocaechififmbbbbbknoalclacl?hl=en
For screens where all the information fits without scrolling, it would
be nice to specify uniform window sizes.
Thanks,
Shawn
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Keeping RefGuide screenshots up to date
Posted by Cassandra Targett <ca...@gmail.com>.
My feeling is we should update all of them, especially if the change you're
talking about isn't made until 8 - a major version feels like a good time
to refresh all the screenshots as there have been enough smaller CSS
changes in 7.x that make them obsolete in many other ways.
IMO, all of them should have also been updated when the Suggestions menu
tab was also added and I've done some as I have time since that was added.
I'm not saying YOU should do all of them, though. I think it would be
enough to do whatever you have time to do now, and file an issue to update
all the screenshots before the 8.0 Guide is done. Maybe some volunteers
will help make it short work, but I'll probably just end up doing all of
them when the time comes.
Selenium might be fine - I've used it only in a proof of concept like 8
years ago for screenshots, so I don't have a great sense for what it's like
to use longer term. If you want to try that, some automated UI testing
would be great.
The Asciidoctor project also has a plugin to automate getting screenshots (
https://github.com/asciidoctor/asciidoctorj-screenshot), but I only know
about it from hearing of it, I've never tried to use it. It seems geared
toward public websites, whereas Selenium probably has more fine-grained
control.
On Thu, Aug 2, 2018 at 5:37 AM Jan Høydahl <ja...@cominvent.com> wrote:
> In SOLR-12613 we'll rename the "Cloud" menu in Admin UI to "Cluster". This
> affects pretty much
> all admin UI screenshots in the Reference Guide, so the next question then
> is "How do we
> keep all those screenshots up to date?". I counted a total of 42 screen
> shots of the UI, many
> which require creating collections, adding data, typing things into the UI
> etc up front.
>
> Due to the work involved, we often tend to update only a few shots and
> leave others as-is even
> if they are inaccurate. Example is the new "Suggestions" menu tab - there
> are 27 screen
> shots in the ref guide which are not updated with that menu option.
>
> For SOLR-12613 I'm tempted to only update the four images in
> "cloud-screens" folder for now.
>
> Perhaps for the future an automated approach can be taken using Selenium,
> as outlined in
> this post:
> https://blog.codeship.com/automating-screenshots-in-documentation/ This
> could
> in first phase be a standalone tool to generate screenshots but could also
> be extended with
> other tests to get some validation of the UI itself, which is completely
> lacking today. WDYT?
>
> --
> Jan Høydahl, search solution architect
> Cominvent AS - www.cominvent.com
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>