Solr Ref Guide Changes - now HTML only

[Cassandra Targett <ct...@apache.org>]

Hi all -

Some have already noticed this change, but to state it formally, as of 8.2,
the Lucene PMC will no longer treat the PDF version of the Solr
Reference Guide as the primary format, and we will no longer release a PDF
version. The Guide will now be available online only.

Some of you may prefer the PDF and will be disappointed by this change. To
explain, there are several reasons why we're doing this:

1. We believe that most in our community rely on the HTML version (at
https://lucene.apache.org/solr/guide), but since our release focus has been
the PDF version, we are not spending time making sure the HTML works as
well as it should and could.
2. The PDF has grown far too large. The 8.1 version is 1,483 pages, and
16Mb. Attempting to cut it back would be complex, and, considering it is a
less effective medium, possibly not worth the effort.
3. The release process held us back from getting the Guide out at the same
time as the artifact release (which is what has happened so far with 8.x
versions of the Guide).
4. Focusing on supporting the PDF first holds us back from several things
we would like to do in the HTML for better content presentation (including
easy-to-maintain architecture diagrams, proper formatting of math formulas,
and more complete language examples, among other things).

So, starting with 8.2 we are making a few changes:

1. The 8.2 version of the Ref Guide has been published in HTML form only (
https://lucene.apache.org/solr/guide/8_2/), and a PDF will not be available.
2. When 8.3 is released (soon), the HTML version will be available online
at the same time, and will be announced together.
3. For those who follow the development list, starting with 8.3 and going
forward a DRAFT version of the Guide will be available online as soon as a
Lucene & Solr release candidate is prepared and a VOTE thread has started.

If you are someone who wishes the PDF would continue, please share your
feedback. While the PDF is not sustainable in its current form - there are
pending changes that will break our current tooling entirely - we could see
if it's possible to find alternate ways to satisfy the same use cases.

Thanks to all of you for your continued support of Lucene and Solr, and we
look forward to making substantial improvements to the Guide in the months
to come.

Regards,
Cassandra

Re: Solr Ref Guide Changes - now HTML only

[Dwane Hall <dw...@hotmail.com>]

Although I don't use the pdf version I highly recommend watching Cassandra's talk from Activate last year ( https://m.youtube.com/watch?v=DixlnxAk08s). In this talk she addresses the challenges of the Solr ref guide including the 'title search' mentioned below and presents a number of options for the guide's future.  It certainly gave me an appreciation for some of the complexities in this part of the Solr project that I'd never fully appreciated before.

The guide has come a long way since the confluence days and continues to evolve with every release. Although the title search is not ideal I'm yet to not find anything I'm looking for with a little creative googling.

That's my tire cents on the matter.
________________________________
From: Alexandre Rafalovitch <ar...@gmail.com>
Sent: Tuesday, 29 October 2019 9:11 AM
To: solr-user <so...@lucene.apache.org>
Subject: Re: Solr Ref Guide Changes - now HTML only

I've done some experiments about indexing RefGuide (from source) into
Solr at: https://github.com/arafalov/solr-refguide-indexing . But the
problem was creating UI, hosting, etc.

There was also a thought (mine) of either shipping RefGuide in Solr
with pre-built index as an example or even just shipping an index with
links to the live version. Both of these were complicated because PDF
was throwing the publication schedule of. And also because we are
trying to make Solr distribution smaller, not bigger. A bit of a
catch-22 there. But maybe now it could be revisited.

Regards,
   Alex.
P.s. A personal offline copy of Solr RefGuide could certainly be built
from source. And it will become even easier to do that soon. But yes,
perhaps a compressed download of HTML version would be a nice
replacement of PDF.

On Tue, 29 Oct 2019 at 09:04, Shawn Heisey <ap...@elyograg.org> wrote:
>
> On 10/28/2019 3:51 PM, Nicolas Paris wrote:
> > I am not very happy with the search engine embedded within the html
> > documentation I admit. Hope this is not solr under the hood :S
>
> It's not Solr under the hood.  It is done by a javascript library that
> runs in the browser.  It only searches page titles, not the whole document.
>
> The fact that a search engine has terrible search in its documentation
> is not lost on us.  We talked about what it would take to use Solr ...
> the infrastructure that would have to be set up and maintaned is
> prohibitive.
>
> We are looking into improving things in this area.  It's going a lot
> slower than we'd like.
>
> Thanks,
> Shawn

Re: Solr Ref Guide Changes - now HTML only

[Alexandre Rafalovitch <ar...@gmail.com>]

I've done some experiments about indexing RefGuide (from source) into
Solr at: https://github.com/arafalov/solr-refguide-indexing . But the
problem was creating UI, hosting, etc.

There was also a thought (mine) of either shipping RefGuide in Solr
with pre-built index as an example or even just shipping an index with
links to the live version. Both of these were complicated because PDF
was throwing the publication schedule of. And also because we are
trying to make Solr distribution smaller, not bigger. A bit of a
catch-22 there. But maybe now it could be revisited.

Regards,
   Alex.
P.s. A personal offline copy of Solr RefGuide could certainly be built
from source. And it will become even easier to do that soon. But yes,
perhaps a compressed download of HTML version would be a nice
replacement of PDF.

On Tue, 29 Oct 2019 at 09:04, Shawn Heisey <ap...@elyograg.org> wrote:
>
> On 10/28/2019 3:51 PM, Nicolas Paris wrote:
> > I am not very happy with the search engine embedded within the html
> > documentation I admit. Hope this is not solr under the hood :S
>
> It's not Solr under the hood.  It is done by a javascript library that
> runs in the browser.  It only searches page titles, not the whole document.
>
> The fact that a search engine has terrible search in its documentation
> is not lost on us.  We talked about what it would take to use Solr ...
> the infrastructure that would have to be set up and maintaned is
> prohibitive.
>
> We are looking into improving things in this area.  It's going a lot
> slower than we'd like.
>
> Thanks,
> Shawn

Re: Solr Ref Guide Changes - now HTML only

[Shawn Heisey <ap...@elyograg.org>]

On 10/28/2019 3:51 PM, Nicolas Paris wrote:
> I am not very happy with the search engine embedded within the html
> documentation I admit. Hope this is not solr under the hood :S

It's not Solr under the hood.  It is done by a javascript library that 
runs in the browser.  It only searches page titles, not the whole document.

The fact that a search engine has terrible search in its documentation 
is not lost on us.  We talked about what it would take to use Solr ... 
the infrastructure that would have to be set up and maintaned is 
prohibitive.

We are looking into improving things in this area.  It's going a lot 
slower than we'd like.

Thanks,
Shawn

Re: Solr Ref Guide Changes - now HTML only

[Nicolas Paris <ni...@riseup.net>]

> If you are someone who wishes the PDF would continue, please share your
> feedback.

I have not particularly explored the documentation format but the
content. However here my thought on this:

Pdf version of solr documentation has two advantages:
1. readable offline
2. make searching easier than the html version


If there were a "one page" version of the html documentation, this
would mitigate searching within the whole. Also a monolitic html page
makes things easier to access offline.(transform back to pdf, ebook..?)

I am not very happy with the search engine embedded within the html
documentation I admit. Hope this is not solr under the hood :S

-- 
nicolas