lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Høydahl <>
Subject Re: Rethinking how we publish the Solr Ref Guide
Date Wed, 18 Sep 2019 21:35:19 GMT
> However Anshum does make a good point that users wouldn't know when the pages have changed.
I think it would be great to have a link on each ref-guide page that shows the last modified
date and links to the history of that page in github

We now have an "Errata" page, which is never used and won't make sense for a live HTML guide.
Perhaps we could instead provide a single HTML page or HTML table as part of or alongside
each guide, showing all commits touching the guide on that branch after the release. Could
probably be baked in as part of the release script. Using the release date or git hash for
the release, it should be possible with some git woodo to bring up a list of commits that
changed the guide after release. That table would normally be very few lines, and would link
directly to the commit that caused the change.

Jan Høydahl, search solution architect
Cominvent AS -

> 18. sep. 2019 kl. 23:26 skrev Houston Putman <>:
> I've had issues with asiidoc features available for the HTML version that didn't work
in PDF, and it was pretty frustrating to work around it. I think just having the site would
be an improvement for the development side, but I've never used the PDF version myself.
> Easy back-porting of documentation would make the solr user experience better too, especially
if the ref-guide is published on each merge. There are lots of features that have been around
for a while that could use better documentation, and we shouldn't restrict better documentation
to the later releases when the features haven't changed since an earlier release. I always
go to the ref guide version that corresponds to the Solr version I'm looking into, and I would
assume most people do as well. If this is the default use case of the ref guide, then I think
backporting as many documentation fixes as possible would be great for user experience (as
long as the documentation doesn't rely on new features).
> However Anshum does make a good point that users wouldn't know when the pages have changed.
I think it would be great to have a link on each ref-guide page that shows the last modified
date and links to the history of that page in github. That at least gives visibility to the
changes, and it could show the date of the most recent update. I'm not sure how hard that
would be to implement, but I would be happy to get something started if anyone else thinks
it's a worthwhile feature.
> - Houston Putman
> On Wed, Sep 18, 2019 at 5:01 PM Jan Høydahl < <>>
> +1 to skip pdf and auto publish ref guides to html on every merge to a branch.
> We could also start publishing a draft 9.x guide there, clearly labeled as work in progress.
> Jan Høydahl
> > 18. sep. 2019 kl. 19:38 skrev Chris Hostetter < <>>:
> > 
> > 
> > First and foremost I should mention: I'm currently in favor of just about 
> > everything Cassandra has suggested here...
> > 
> > : So, I propose making some radical changes. My ideas here require a shift
> > : from thinking of the Guide as a release artifact like the binaries to
> > : thinking of it similar to how we treat javadocs. These ideas also allow us
> > 
> > I would actually go farther then that, and suggest that moving forward the 
> > "official ref-guide" for "Solr X.Y" (hosted on <>)

> > automatically be updated anytime anyone pushes edits to brach_X_Y -- as 
> > opposed to our javadocs for X.Y.0 which *might* be rebuilt for formatting 
> > purposes (something we've done in the past) but no *code* (ie: "content") 
> > changes on branch_X_Y would be reflected ... those would be part of the 
> > "bug fix" release X.Y.1, which would have it's own javadocs.  But 
> > meanwhile, the ref-guide for X.Y could/would be updated with doc 
> > improvements even if there were no bug-fix releases from branch_X_Y.
> > 
> > 
> > : -- By ASF policy, release artifacts must be produced on a machine
> > : controlled by the committer. However, the point here is that the Ref Guide
> > : would no longer be a release artifact, so I think that gets us around that
> > : rule? If anyone sees this differently that would change things here a
> > : little bit.
> > 
> > FWIW: My understand from years ago was that the policy was unambiguious:
> > 1) a release vote is neccessary for anything that goes on <>
> > 2) any "downloads" should come from <>
> > "browseable html" docs on <>
wouldn't require a 
> > VOTE, but if we want to keep providing a provide a big PDF or zip file of 
> > all the HTML that would require a vote -- *BUT* it seems like the rules 
> > are more ambiguious now, particularly regarding "documentation" downloads 
> > ... ex: i know openoffice provides downloadable PDFs of their user guide 
> > from their wiki, pretty sure they don't vote on that.
> > 
> > 
> > 
> > : PS, As for the PDF, I believe there are mixed opinions about it. Some rely
> > 
> > As someone who has been a long time advocate of the PDF, and of treating 
> > it as an "official (VOTEed) release artifact" i wanted to toss out some 
> > historical context, and notes on how/why my own feelings have evolved.
> > 
> > Once upon a time, Solr had shit-all user documentation.  We had nothing 
> > but our (moin moin) wiki, which was a hodge-podge mess, an amalgmaation 
> > mix of docs written by developers as features were created, and "tips" 
> > pages written by users with thoughts on how to do things, and none of it 
> > was well organized and all of it was sprinkled with "this feature 
> > was added in version X.Y but changed defaults to FOO in version X.Z..."
> > 
> > When the lucidworks created the first few versions of the ref-guide using 
> > Confluence as a CMS, and donated it to the ASF, i (and others) really felt 
> > it was important that end users could see this new material as official, 
> > authoritative, and "specific" (to each version of Solr) ... we did *NOT* 
> > want people to start thinking of it as "just another wiki".  Since 
> > confluence didn't have an easy way to "branch" the entire space for 
> > each version (not w/o a lot of infra assistance) and *did* provide an easy 
> > way to publish the entire guide as a PDF, doing that and voting on the 
> > resulting PDF as a true "documentation release artifact" seemed like a 
> > good way to ensure we not only had version specific "snapshots" of the 
> > content, but gave these PDFs more "legtimacy" as being "official".
> > 
> > When we migrated to using asciidoctor, i (and others?) really felt like it 
> > was important to keep the continuity of having an "official PDF release 
> > artifact" since that was what our users were use to to ensure they were 
> > looking a the "correct" ref-guide version.  (With the old confluence CMS, 
> > the only "browseable" html view of the content corrisponded to the latest 
> > branch_YYY_x, with a handful of pages for trunk only features).  But of 
> > course: being able to branch the ref-guide source alongwith the code, and 
> > being able to build & host browseable HTML pages for all the content was a 
> > really nice value add.
> > 
> > The project, our documentation, and the communities views/experience with 
> > our documetation aren't the same as they were 6+ years ago.  As already 
> > mentioned by a few people: it seems like most users browse/read the 
> > (version specific) ref-guide hosted on <>.
 The handful of 
> > users who really care about "offline" access to the content on their 
> > laptops can probably build the HTML site locally from source just as 
> > easily as they can downloda the PDF.
> > 
> > So while My 2013 self, and my 2015 self, and even my 2017 self would have 
> > been really adament about having an "official voted (PDF) release 
> > artifact" for the ref-guide ... my 2019 self realizes that the world has 
> > changed, and we're just making more work for ourselves -- at an 
> > opportunity cost of having an "official" (hosted) version of the ref-guide 
> > with more accurate "post release" doc fixes and more dynamic presentation 
> > features that just aren't possible in the PDF.
> > 
> > 
> > -Hoss
> > <>
> > 
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: <>
> > For additional commands, e-mail: <>
> > 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: <>
> For additional commands, e-mail: <>

View raw message