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 <jan....@cominvent.com> wrote: > +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 <hossman_luc...@fucit.org > >: > > > > > > 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 > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org > For additional commands, e-mail: dev-h...@lucene.apache.org > >
