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 lucene.apache.org) 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 dist.apache.org 2) any "downloads" should come from dist.apache.org ...so "browseable html" docs on lucene.apache.org 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 lucene.apache.org. 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 http://www.lucidworks.com/ --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
