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:01:24 GMT
+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