> 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 - www.cominvent.com > 18. sep. 2019 kl. 23:26 skrev Houston Putman <houstonput...@gmail.com>: > > 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 > <mailto: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 > > <mailto: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 > > <http://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 > > <http://dist.apache.org/> > > 2) any "downloads" should come from dist.apache.org > > <http://dist.apache.org/> > > ...so "browseable html" docs on lucene.apache.org > > <http://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 > > <http://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/ <http://www.lucidworks.com/> > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org > > <mailto:dev-unsubscr...@lucene.apache.org> > > For additional commands, e-mail: dev-h...@lucene.apache.org > > <mailto:dev-h...@lucene.apache.org> > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org > <mailto:dev-unsubscr...@lucene.apache.org> > For additional commands, e-mail: dev-h...@lucene.apache.org > <mailto:dev-h...@lucene.apache.org> >
