+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 <[email protected]>: > > > 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: [email protected] > For additional commands, e-mail: [email protected] > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
