lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Høydahl <jan....@cominvent.com>
Subject Re: Solr RefGuide Errata page wrong link
Date Fri, 11 May 2018 12:11:26 GMT
Do we have Google analytics stats for how often the Errata page in the online refGuide is visited?
Eh, since the link from PDF is broken that number may be 0 :-)

I agree that most people may be unaware of that page, and perhaps the page is not needed since
we tend to release new minor versions fairly often, so the amount of time the RefGuide is
in error is low.
I also think that most people wanting to upgrade probably first check CHANGES.txt and may
never consult the RefGuide, so even if we published some important info on that page it may
not be read.
If we kill the whole concept of an Errata, perhaps we should simply direct users to https://lucene.apache.org/solr/news.html
<https://lucene.apache.org/solr/news.html> where we announce releases and CVEs. And
then if we wish to notify users about other critical flaws such as SOLR-12321, it is much
easier to add a news entry to the page than to republish the guide?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com

> 10. mai 2018 kl. 15:47 skrev Cassandra Targett <casstargett@gmail.com>:
> 
> The Errata page isn't the place for "We released 7.3 and then found a bug" IMO. There
would be hundreds of candidates for that. SOLR-12321 isn't an issue that we missed documenting
- it was a bug that was not discovered until later.
> 
> But you missed my point - if people have had ideas for how to use Errata (or any similar
page) but haven't ever done anything about it, are they going to suddenly start? Maybe yesterday
was the first time you personally thought of anything to do with that page; that's fine, but
my point is that ideas are easy, actions are harder.
> 
> Let's understand up front that adding stuff to the Errata page would require a re-release
of the HTML version of the Ref Guide. This isn't that hard and doesn't require a VOTE by design,
but we have no process for it yet.
> 
> The Errata page historically comes from the Confluence days and it made much more sense
then. We couldn't have versioned docs so we couldn't re-release the Ref Guide if we found
a glaring problem with the documentation itself ("We said this feature does X, it really does
Y"). We could make live edits, though. But even then I remember *one* time that someone used
it.
> 
> Now if that happens we can re-release the Ref Guide. This has come up a couple times
when people thought about doing that. But once it was clear they would need to be the ones
to work through some decisions about how to do it, the idea was abandoned.
> 
> Which proves my point - the idea of re-releasing the Ref Guide for any reason is easy,
but as soon as I say we don't already have all the details worked out, it becomes harder and
people move on. I'm really not trying to bash anyone, it's just human nature and we're all
juggling multiple priorities. You can tell it hasn't reached the top of my list yet.
> 
> Major bugs found after release could be a very good thing to put in the Ref Guide - I'd
love it, really - but it would need some guidelines for what goes there, and a process for
updating and publishing the changes that anyone can (and would) follow. I would advocate for
changing the name of the page in that case - "Issues Found After Release" would be better
than "Errata" - but that's ultimately only a tiny portion of the decisions that would need
to be made. The bigger questions are around how it gets from the source code to the online
site and *who* does that regularly IMO.
> 
> Maybe it's annoying that I keep bringing the conversation back to how we'll do these
things, but I'm a practical person by nature and my mind very naturally jumps to figuring
out obstacles to good ideas and trying to understand what needs to happen to overcome them.
> 
> Cassandra
> 
> On Wed, May 9, 2018 at 5:57 PM Jan Høydahl <jan.asf@cominvent.com <mailto:jan.asf@cominvent.com>>
wrote:
> One candidate for an errata entry could be https://issues.apache.org/jira/browse/SOLR-12321
<https://issues.apache.org/jira/browse/SOLR-12321> do document that 7.3 broke back compat
with 7.2. This should normally have been documented in CHANGES Upgrade Notes. 
> 
> Perhaps there should be a link to the errata page from the top of CHANGES.txt, and from
the beginning of the reference guide such as "About This Guide"?
> 
> --
> Jan Høydahl, search solution architect
> Cominvent AS - www.cominvent.com <http://www.cominvent.com/>
> 
>> 9. mai 2018 kl. 23:54 skrev Cassandra Targett <casstargett@gmail.com <mailto:casstargett@gmail.com>>:
>> 
>> Yeah, you're right - it's parameterized using a bad parameter. I've often thought,
though, that it should go away - we never update it and having a page that refers to itself
online is weird. Thoughts? Anyone really want this page and intend to update it? I likely
won't ever unless I get a ton of extra time somehow.
>> 
>> As for the comments, I filed https://issues.apache.org/jira/browse/SOLR-12018 <https://issues.apache.org/jira/browse/SOLR-12018>
months ago.
>> 
>> On Wed, May 9, 2018 at 2:51 PM Jan Høydahl <jan.asf@cominvent.com <mailto:jan.asf@cominvent.com>>
wrote:
>> See https://lucene.apache.org/solr/guide/7_3/errata.html <https://lucene.apache.org/solr/guide/7_3/errata.html>
>> The link on that page says /7.3/… but should be /7_3/… so it is a 404 now, and
probably also in the PDF.
>> 
>> PS: The Apache Comments section is not active
>> 
>> --
>> Jan Høydahl, search solution architect
>> Cominvent AS - www.cominvent.com <http://www.cominvent.com/>
>> 
>> 
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org <mailto:dev-unsubscribe@lucene.apache.org>
>> For additional commands, e-mail: dev-help@lucene.apache.org <mailto:dev-help@lucene.apache.org>
>> 
> 


Mime
View raw message