You are viewing a plain text version of this content. The canonical link for it is here.
Posted to solr-user@lucene.apache.org by Cassandra Targett <ct...@apache.org> on 2020/04/28 20:12:59 UTC
Solr Ref Guide Redesign coming in 8.6
The PMC would like to engage the Solr user community for feedback on an
extensive redesign of the Solr Reference Guide I've just committed to the
master (future 9.0) branch.
You can see the new design from our Jenkins build of master:
https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-master/javadoc/
The hope is that you will receive these changes positively. If so, we'll
use this for the upcoming 8.6 Ref Guide and future releases. We also may
re-publish earlier 8.x versions so they use this design.
I embarked on this project last December simply as an attempt to upgrade
the version of Bootstrap used by the Guide. After a couple of days, I'd
changed the layout entirely. In the ensuing few months I've tried to iron
out the kinks and made some extensive changes to the "backend" (the CSS,
JavaScript, etc.).
I'm no graphic designer, but some of my guiding thoughts were to try to
make full use of the browser window, improve responsiveness for different
sized screens, and just give it a more modern feel. The full list of what
has changed is detailed in the Jira issue if you are interested:
https://issues.apache.org/jira/browse/SOLR-14173
This is Phase 1 of several changes. There is one glaring remaining issue,
which is that our list of top-level categories is too long for the new
design. I've punted fixing that to Phase 2, which will be an extensive
re-consideration of how the Ref Guide is organized with the goal of
trimming down the top-level categories to only 4-6. SOLR-14444 will track
phase 2.
One last thing to note: this redesign really only changes the presentation
of the pages and some of the framework under the hood - it doesn't yet add
full-text search. All of the obstacles to providing search still exist, but
please know that we fully understand frustration on this point and still
hope to fix it.
I look forward to hearing your feedback in this thread.
Best,
Cassandra
Re: Solr Ref Guide Redesign coming in 8.6
Posted by matthew sporleder <ms...@gmail.com>.
I highly recommend a version selector in the header! I am *always*
landing on 6.x docs from google.
On Tue, Apr 28, 2020 at 5:18 PM Cassandra Targett <ct...@apache.org> wrote:
>
> In case the list breaks the URL to view the Jenkins build, here's a shorter
> URL:
>
> https://s.apache.org/df7ew.
>
> On Tue, Apr 28, 2020 at 3:12 PM Cassandra Targett <ct...@apache.org>
> wrote:
>
> > The PMC would like to engage the Solr user community for feedback on an
> > extensive redesign of the Solr Reference Guide I've just committed to the
> > master (future 9.0) branch.
> >
> > You can see the new design from our Jenkins build of master:
> >
> > https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-master/javadoc/
> >
> > The hope is that you will receive these changes positively. If so, we'll
> > use this for the upcoming 8.6 Ref Guide and future releases. We also may
> > re-publish earlier 8.x versions so they use this design.
> >
> > I embarked on this project last December simply as an attempt to upgrade
> > the version of Bootstrap used by the Guide. After a couple of days, I'd
> > changed the layout entirely. In the ensuing few months I've tried to iron
> > out the kinks and made some extensive changes to the "backend" (the CSS,
> > JavaScript, etc.).
> >
> > I'm no graphic designer, but some of my guiding thoughts were to try to
> > make full use of the browser window, improve responsiveness for different
> > sized screens, and just give it a more modern feel. The full list of what
> > has changed is detailed in the Jira issue if you are interested:
> > https://issues.apache.org/jira/browse/SOLR-14173
> >
> > This is Phase 1 of several changes. There is one glaring remaining issue,
> > which is that our list of top-level categories is too long for the new
> > design. I've punted fixing that to Phase 2, which will be an extensive
> > re-consideration of how the Ref Guide is organized with the goal of
> > trimming down the top-level categories to only 4-6. SOLR-14444 will track
> > phase 2.
> >
> > One last thing to note: this redesign really only changes the presentation
> > of the pages and some of the framework under the hood - it doesn't yet add
> > full-text search. All of the obstacles to providing search still exist, but
> > please know that we fully understand frustration on this point and still
> > hope to fix it.
> >
> > I look forward to hearing your feedback in this thread.
> >
> > Best,
> > Cassandra
> >
Re: Solr Ref Guide Redesign coming in 8.6
Posted by Cassandra Targett <ct...@apache.org>.
To respond to the feedback so far:
Version picker: This is more complex than it may be initially assumed
because of the way we publish the site. Since we use a static site
generator, each page is a standalone HTML file. To add a version picker to
an older version that includes all the latest versions, we'd need to
republish all the older versions every time we published a new one. We
could get around this by pointing a version picker to a location we update
each time (but still today would need to republish all the older versions
to add it at all), which was harder to do in the past due to how the Solr
website as a whole was published. I wanted to try to address this problem
in what I'm calling Phase 3 - moving to a different static site generator
that supports multiple versions in a more native way but maybe I can find a
simple stopgap until then.
Jumpiness while hovering over nav items: The font size isn't actually
different when you hover or select a nav item, it's just bolded which makes
it overrun the allotted space and wrap. I made it bolded in response to
other feedback I got earlier on that there was not enough differentiation
between selected and not-selected items but didn't notice the jumpiness (I
had to make my screen quite large to duplicate it, and when I looked at the
Guide on larger screens earlier I was usually looking at some other problem
and just didn't notice). I'll play with it a little and find another way to
differentiate the items without bolding them.
Thanks for your comments so far!
On Wed, Apr 29, 2020 at 2:56 AM Colvin Cowie <co...@gmail.com>
wrote:
> In addition to those points, I think it generally does look good but the
> thing I've noticed is that increase in text size on rollover in the menu
> makes it quite jumpy:
> https://drive.google.com/open?id=15EF0T_C_l8OIDuW8QHOFunL4VzxtyVyb
>
> On Wed, 29 Apr 2020 at 08:15, Bernd Fehling <
> bernd.fehling@uni-bielefeld.de>
> wrote:
>
> > +1
> >
> > And a fully indexed search for the Ref Guide.
> > I have to use Google to search for infos in Ref Guide of a search engine.
> > :-(
> >
> >
> > Am 29.04.20 um 02:11 schrieb matthew sporleder:
> > > I highly recommend a version selector in the header! I am *always*
> > > landing on 6.x docs from google.
> > >
> > > On Tue, Apr 28, 2020 at 5:18 PM Cassandra Targett <ctargett@apache.org
> >
> > wrote:
> > >>
> > >> In case the list breaks the URL to view the Jenkins build, here's a
> > shorter
> > >> URL:
> > >>
> > >> https://s.apache.org/df7ew.
> > >>
> > >> On Tue, Apr 28, 2020 at 3:12 PM Cassandra Targett <
> ctargett@apache.org>
> > >> wrote:
> > >>
> > >>> The PMC would like to engage the Solr user community for feedback on
> an
> > >>> extensive redesign of the Solr Reference Guide I've just committed to
> > the
> > >>> master (future 9.0) branch.
> > >>>
> > >>> You can see the new design from our Jenkins build of master:
> > >>>
> > >>>
> >
> https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-master/javadoc/
> > >>>
> > >>> The hope is that you will receive these changes positively. If so,
> > we'll
> > >>> use this for the upcoming 8.6 Ref Guide and future releases. We also
> > may
> > >>> re-publish earlier 8.x versions so they use this design.
> > >>>
> > >>> I embarked on this project last December simply as an attempt to
> > upgrade
> > >>> the version of Bootstrap used by the Guide. After a couple of days,
> I'd
> > >>> changed the layout entirely. In the ensuing few months I've tried to
> > iron
> > >>> out the kinks and made some extensive changes to the "backend" (the
> > CSS,
> > >>> JavaScript, etc.).
> > >>>
> > >>> I'm no graphic designer, but some of my guiding thoughts were to try
> to
> > >>> make full use of the browser window, improve responsiveness for
> > different
> > >>> sized screens, and just give it a more modern feel. The full list of
> > what
> > >>> has changed is detailed in the Jira issue if you are interested:
> > >>> https://issues.apache.org/jira/browse/SOLR-14173
> > >>>
> > >>> This is Phase 1 of several changes. There is one glaring remaining
> > issue,
> > >>> which is that our list of top-level categories is too long for the
> new
> > >>> design. I've punted fixing that to Phase 2, which will be an
> extensive
> > >>> re-consideration of how the Ref Guide is organized with the goal of
> > >>> trimming down the top-level categories to only 4-6. SOLR-14444 will
> > track
> > >>> phase 2.
> > >>>
> > >>> One last thing to note: this redesign really only changes the
> > presentation
> > >>> of the pages and some of the framework under the hood - it doesn't
> yet
> > add
> > >>> full-text search. All of the obstacles to providing search still
> > exist, but
> > >>> please know that we fully understand frustration on this point and
> > still
> > >>> hope to fix it.
> > >>>
> > >>> I look forward to hearing your feedback in this thread.
> > >>>
> > >>> Best,
> > >>> Cassandra
> > >>>
> >
>
Re: Solr Ref Guide Redesign coming in 8.6
Posted by Colvin Cowie <co...@gmail.com>.
In addition to those points, I think it generally does look good but the
thing I've noticed is that increase in text size on rollover in the menu
makes it quite jumpy:
https://drive.google.com/open?id=15EF0T_C_l8OIDuW8QHOFunL4VzxtyVyb
On Wed, 29 Apr 2020 at 08:15, Bernd Fehling <be...@uni-bielefeld.de>
wrote:
> +1
>
> And a fully indexed search for the Ref Guide.
> I have to use Google to search for infos in Ref Guide of a search engine.
> :-(
>
>
> Am 29.04.20 um 02:11 schrieb matthew sporleder:
> > I highly recommend a version selector in the header! I am *always*
> > landing on 6.x docs from google.
> >
> > On Tue, Apr 28, 2020 at 5:18 PM Cassandra Targett <ct...@apache.org>
> wrote:
> >>
> >> In case the list breaks the URL to view the Jenkins build, here's a
> shorter
> >> URL:
> >>
> >> https://s.apache.org/df7ew.
> >>
> >> On Tue, Apr 28, 2020 at 3:12 PM Cassandra Targett <ct...@apache.org>
> >> wrote:
> >>
> >>> The PMC would like to engage the Solr user community for feedback on an
> >>> extensive redesign of the Solr Reference Guide I've just committed to
> the
> >>> master (future 9.0) branch.
> >>>
> >>> You can see the new design from our Jenkins build of master:
> >>>
> >>>
> https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-master/javadoc/
> >>>
> >>> The hope is that you will receive these changes positively. If so,
> we'll
> >>> use this for the upcoming 8.6 Ref Guide and future releases. We also
> may
> >>> re-publish earlier 8.x versions so they use this design.
> >>>
> >>> I embarked on this project last December simply as an attempt to
> upgrade
> >>> the version of Bootstrap used by the Guide. After a couple of days, I'd
> >>> changed the layout entirely. In the ensuing few months I've tried to
> iron
> >>> out the kinks and made some extensive changes to the "backend" (the
> CSS,
> >>> JavaScript, etc.).
> >>>
> >>> I'm no graphic designer, but some of my guiding thoughts were to try to
> >>> make full use of the browser window, improve responsiveness for
> different
> >>> sized screens, and just give it a more modern feel. The full list of
> what
> >>> has changed is detailed in the Jira issue if you are interested:
> >>> https://issues.apache.org/jira/browse/SOLR-14173
> >>>
> >>> This is Phase 1 of several changes. There is one glaring remaining
> issue,
> >>> which is that our list of top-level categories is too long for the new
> >>> design. I've punted fixing that to Phase 2, which will be an extensive
> >>> re-consideration of how the Ref Guide is organized with the goal of
> >>> trimming down the top-level categories to only 4-6. SOLR-14444 will
> track
> >>> phase 2.
> >>>
> >>> One last thing to note: this redesign really only changes the
> presentation
> >>> of the pages and some of the framework under the hood - it doesn't yet
> add
> >>> full-text search. All of the obstacles to providing search still
> exist, but
> >>> please know that we fully understand frustration on this point and
> still
> >>> hope to fix it.
> >>>
> >>> I look forward to hearing your feedback in this thread.
> >>>
> >>> Best,
> >>> Cassandra
> >>>
>
Re: Solr Ref Guide Redesign coming in 8.6
Posted by Bernd Fehling <be...@uni-bielefeld.de>.
+1
And a fully indexed search for the Ref Guide.
I have to use Google to search for infos in Ref Guide of a search engine. :-(
Am 29.04.20 um 02:11 schrieb matthew sporleder:
> I highly recommend a version selector in the header! I am *always*
> landing on 6.x docs from google.
>
> On Tue, Apr 28, 2020 at 5:18 PM Cassandra Targett <ct...@apache.org> wrote:
>>
>> In case the list breaks the URL to view the Jenkins build, here's a shorter
>> URL:
>>
>> https://s.apache.org/df7ew.
>>
>> On Tue, Apr 28, 2020 at 3:12 PM Cassandra Targett <ct...@apache.org>
>> wrote:
>>
>>> The PMC would like to engage the Solr user community for feedback on an
>>> extensive redesign of the Solr Reference Guide I've just committed to the
>>> master (future 9.0) branch.
>>>
>>> You can see the new design from our Jenkins build of master:
>>>
>>> https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-master/javadoc/
>>>
>>> The hope is that you will receive these changes positively. If so, we'll
>>> use this for the upcoming 8.6 Ref Guide and future releases. We also may
>>> re-publish earlier 8.x versions so they use this design.
>>>
>>> I embarked on this project last December simply as an attempt to upgrade
>>> the version of Bootstrap used by the Guide. After a couple of days, I'd
>>> changed the layout entirely. In the ensuing few months I've tried to iron
>>> out the kinks and made some extensive changes to the "backend" (the CSS,
>>> JavaScript, etc.).
>>>
>>> I'm no graphic designer, but some of my guiding thoughts were to try to
>>> make full use of the browser window, improve responsiveness for different
>>> sized screens, and just give it a more modern feel. The full list of what
>>> has changed is detailed in the Jira issue if you are interested:
>>> https://issues.apache.org/jira/browse/SOLR-14173
>>>
>>> This is Phase 1 of several changes. There is one glaring remaining issue,
>>> which is that our list of top-level categories is too long for the new
>>> design. I've punted fixing that to Phase 2, which will be an extensive
>>> re-consideration of how the Ref Guide is organized with the goal of
>>> trimming down the top-level categories to only 4-6. SOLR-14444 will track
>>> phase 2.
>>>
>>> One last thing to note: this redesign really only changes the presentation
>>> of the pages and some of the framework under the hood - it doesn't yet add
>>> full-text search. All of the obstacles to providing search still exist, but
>>> please know that we fully understand frustration on this point and still
>>> hope to fix it.
>>>
>>> I look forward to hearing your feedback in this thread.
>>>
>>> Best,
>>> Cassandra
>>>
Re: Solr Ref Guide Redesign coming in 8.6
Posted by Cassandra Targett <ct...@apache.org>.
In case the list breaks the URL to view the Jenkins build, here's a shorter
URL:
https://s.apache.org/df7ew.
On Tue, Apr 28, 2020 at 3:12 PM Cassandra Targett <ct...@apache.org>
wrote:
> The PMC would like to engage the Solr user community for feedback on an
> extensive redesign of the Solr Reference Guide I've just committed to the
> master (future 9.0) branch.
>
> You can see the new design from our Jenkins build of master:
>
> https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-master/javadoc/
>
> The hope is that you will receive these changes positively. If so, we'll
> use this for the upcoming 8.6 Ref Guide and future releases. We also may
> re-publish earlier 8.x versions so they use this design.
>
> I embarked on this project last December simply as an attempt to upgrade
> the version of Bootstrap used by the Guide. After a couple of days, I'd
> changed the layout entirely. In the ensuing few months I've tried to iron
> out the kinks and made some extensive changes to the "backend" (the CSS,
> JavaScript, etc.).
>
> I'm no graphic designer, but some of my guiding thoughts were to try to
> make full use of the browser window, improve responsiveness for different
> sized screens, and just give it a more modern feel. The full list of what
> has changed is detailed in the Jira issue if you are interested:
> https://issues.apache.org/jira/browse/SOLR-14173
>
> This is Phase 1 of several changes. There is one glaring remaining issue,
> which is that our list of top-level categories is too long for the new
> design. I've punted fixing that to Phase 2, which will be an extensive
> re-consideration of how the Ref Guide is organized with the goal of
> trimming down the top-level categories to only 4-6. SOLR-14444 will track
> phase 2.
>
> One last thing to note: this redesign really only changes the presentation
> of the pages and some of the framework under the hood - it doesn't yet add
> full-text search. All of the obstacles to providing search still exist, but
> please know that we fully understand frustration on this point and still
> hope to fix it.
>
> I look forward to hearing your feedback in this thread.
>
> Best,
> Cassandra
>
Re: Solr Ref Guide Redesign coming in 8.6
Posted by S G <sg...@gmail.com>.
I really like the docs and version selecting provided by Graylog
https://docs.graylog.org/en/3.2/
It says this on the bottom:
Built with Sphinx <http://sphinx-doc.org/> using a theme
<https://github.com/rtfd/sphinx_rtd_theme> provided by Read the Docs
<https://readthedocs.org/>.
I do not have any experience with Sphinx or Read the Docs.
Here is the version selector and download menu:
[image: Screen Shot 2020-05-04 at 8.21.52 AM.png]
On Wed, Apr 29, 2020 at 11:30 AM Cassandra Targett <ca...@gmail.com>
wrote:
> > This design still has a minor annoyance that I have noted in the past:
> > in the table of contents pane it is easy to open a subtree, but the
> > only way to close it is to open another one. Obviously not a big
> > deal.
>
> Thanks for pointing that out, it helped me find a big problem which was
> that I used the wrong build of JQuery to support using the caret to
> open/close the subtree. It should work now to open a subtree independently
> of clicking the heading, and should also close the tree.
> > I'll probably spend too much time researching how to widen the
> > razor-thin scrollbar in the TOC panel, since it seems to be
> > independent of the way I spent too much time fixing the browser's own
> > inadequate scrollbar width. :-) Also, the thumb's color is so close to
> > the surrounding color that it's really hard to see. And for some
> > reason when I use the mouse wheel to scroll the TOC, when it gets to
> > the top or the bottom the content pane starts scrolling instead, which
> > is surprising and mildly inconvenient. Final picky point: the
> > scrolling is *very* insensitive -- takes a lot of wheel motion to move
> > the panel just a bit.
>
> I’m not totally following all of this, but if I assume you mean the left
> sidebar navigation (and not an in-page TOC) then my answer to at least part
> of it is to pare down the list of top-level topics so you don’t have to
> scroll it at all and then the only scrolling you need to do is for the
> content itself. That’s what I want to do in Phase 2, so there are several
> things in the behavior of the sidebar I’m purposely ignoring for now. Some
> will go away with a new organization and new things will be introduced that
> will need to be fixed, so to save myself some time I’m waiting to fix all
> of it at once.
>
Re: Solr Ref Guide Redesign coming in 8.6
Posted by Cassandra Targett <ca...@gmail.com>.
> This design still has a minor annoyance that I have noted in the past:
> in the table of contents pane it is easy to open a subtree, but the
> only way to close it is to open another one. Obviously not a big
> deal.
Thanks for pointing that out, it helped me find a big problem which was that I used the wrong build of JQuery to support using the caret to open/close the subtree. It should work now to open a subtree independently of clicking the heading, and should also close the tree.
> I'll probably spend too much time researching how to widen the
> razor-thin scrollbar in the TOC panel, since it seems to be
> independent of the way I spent too much time fixing the browser's own
> inadequate scrollbar width. :-) Also, the thumb's color is so close to
> the surrounding color that it's really hard to see. And for some
> reason when I use the mouse wheel to scroll the TOC, when it gets to
> the top or the bottom the content pane starts scrolling instead, which
> is surprising and mildly inconvenient. Final picky point: the
> scrolling is *very* insensitive -- takes a lot of wheel motion to move
> the panel just a bit.
I’m not totally following all of this, but if I assume you mean the left sidebar navigation (and not an in-page TOC) then my answer to at least part of it is to pare down the list of top-level topics so you don’t have to scroll it at all and then the only scrolling you need to do is for the content itself. That’s what I want to do in Phase 2, so there are several things in the behavior of the sidebar I’m purposely ignoring for now. Some will go away with a new organization and new things will be introduced that will need to be fixed, so to save myself some time I’m waiting to fix all of it at once.
Re: Solr Ref Guide Redesign coming in 8.6
Posted by "Mark H. Wood" <mw...@iupui.edu>.
At first glance, I have no big issues. It looks clean and functional,
and I like that. I think it will work well enough for me.
This design still has a minor annoyance that I have noted in the past:
in the table of contents pane it is easy to open a subtree, but the
only way to close it is to open another one. Obviously not a big
deal.
I'll probably spend too much time researching how to widen the
razor-thin scrollbar in the TOC panel, since it seems to be
independent of the way I spent too much time fixing the browser's own
inadequate scrollbar width. :-) Also, the thumb's color is so close to
the surrounding color that it's really hard to see. And for some
reason when I use the mouse wheel to scroll the TOC, when it gets to
the top or the bottom the content pane starts scrolling instead, which
is surprising and mildly inconvenient. Final picky point: the
scrolling is *very* insensitive -- takes a lot of wheel motion to move
the panel just a bit.
(I'm aware that a lot of the things I complain about in "modern" web
sites are the things that make them "modern". So, I'm an old fossil. :-)
Firefox 68.7.0esr, Gentoo Linux.
--
Mark H. Wood
Lead Technology Analyst
University Library
Indiana University - Purdue University Indianapolis
755 W. Michigan Street
Indianapolis, IN 46202
317-274-0749
www.ulib.iupui.edu