Rethinking how we publish the Solr Ref Guide

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

Rethinking how we publish the Solr Ref Guide

Cassandra Targett
The delays getting the Ref Guides for 8.x releases out have caused me to think a bit about the Ref Guide publication process. It seems clear others aren't able to pick up the process when I can't and I’m sure there are a million individual reasons for that so I don't intend to shame or blame anyone, but a process that relies on a single person in a community our size isn’t a very good one. And, if I think about _why_ we have a process like we have today [1], I’m not sure it makes a ton of sense any longer.

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 to finally get to the goal of unifying these currently separate processes.

1. Make the HTML version the “official” version.
-- What to do with the PDF is TBD after that decision, see below.

2. Stop voting for the Ref Guide release as a separate VOTE thread.

3. Jenkins jobs are already created when a release branch is cut. We can change these jobs so they always automatically push the HTML version to the website, although before the version binaries are released the pages would still have a DRAFT watermark across them [2].
-- 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.
-- I know other projects have similar Jenkins->publish workflows, but I’m not sure exactly what’s involved in setting it up. Might need to discuss with the Infra team and other changes may be required depending.
-- The goal, though, is to automate this as much as possible.

4. When a VOTE has passed, a simple step could be added to the release process to run a Jenkins job to regenerate the HTML pages without the current DRAFT watermark and automatically push them to the production website.
-- Since we usually leave branch jobs configured-but-disabled for a little bit in case a patch release is necessary, typos or other things fixed “post-release" could be fixed and the Ref Guide Jenkins job would just push new commits to the branch to the live production site.
-- These updates would be done without the DRAFT status, since the Ref Guide in that branch is now considered “live”.
-- This part of the idea would allow us to more easily backport any docs changes and re-publish the Guide without having to do a new vote, which we would need today. This might be rare, but it is a question that comes up from time-to-time. I feel that if the publication process was easier, we might fix things retroactively more often.

5. Some tooling would be nice to automate parts of the copy edit process I do today, so it can be run by any committer at any point in the process. This can follow on later. I have a list.

So, that's the idea in a nutshell - thoughts?

[1] Current release process: https://lucene.apache.org/solr/guide/8_1/how-to-contribute.html#ref-guide-publication-process
[2] Example of DRAFT watermark (it's all CSS, it could look however we want it to): https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-8.x/javadoc/

PS, As for the PDF, I believe there are mixed opinions about it. Some rely on it, others only use it when they need it (portability, easier to search, etc.), others don’t ever look at it. The fact is it’s over 1600 pages, and that’s just really too big. Joel is about to add a significant number of new images as part of a new "visual" guide (see SOLR-13105), which will make it even longer and bigger. Trying to split it to make it smaller would bring in a lot of complexity with how to deal with links between pages that end up in different PDF files (believe me, I've done it before). And finally, it holds us back a little - some things we could do with HTML/JS can't be done in PDF. I’d be fine continuing to produce it, just not as our main artifact. We could have Jenkins push that also to the SVN dist/dev repo where it currently lives.

Cassandra

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Alexandre Rafalovitch
+1 on the suggested process. +1 on PDF just being too big, though it
is fun to quote the page count.

An additional idea piggy-backing on this is that in step 4, we could
also automatically build a local example/index that links to the
public version. So, people could search the guide locally and that
would link to the known public URLs for the real HTML.

Regards,
   Alex.

On Wed, 18 Sep 2019 at 12:07, Cassandra Targett <[hidden email]> wrote:

>
> The delays getting the Ref Guides for 8.x releases out have caused me to think a bit about the Ref Guide publication process. It seems clear others aren't able to pick up the process when I can't and I’m sure there are a million individual reasons for that so I don't intend to shame or blame anyone, but a process that relies on a single person in a community our size isn’t a very good one. And, if I think about _why_ we have a process like we have today [1], I’m not sure it makes a ton of sense any longer.
>
> 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 to finally get to the goal of unifying these currently separate processes.
>
> 1. Make the HTML version the “official” version.
> -- What to do with the PDF is TBD after that decision, see below.
>
> 2. Stop voting for the Ref Guide release as a separate VOTE thread.
>
> 3. Jenkins jobs are already created when a release branch is cut. We can change these jobs so they always automatically push the HTML version to the website, although before the version binaries are released the pages would still have a DRAFT watermark across them [2].
> -- 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.
> -- I know other projects have similar Jenkins->publish workflows, but I’m not sure exactly what’s involved in setting it up. Might need to discuss with the Infra team and other changes may be required depending.
> -- The goal, though, is to automate this as much as possible.
>
> 4. When a VOTE has passed, a simple step could be added to the release process to run a Jenkins job to regenerate the HTML pages without the current DRAFT watermark and automatically push them to the production website.
> -- Since we usually leave branch jobs configured-but-disabled for a little bit in case a patch release is necessary, typos or other things fixed “post-release" could be fixed and the Ref Guide Jenkins job would just push new commits to the branch to the live production site.
> -- These updates would be done without the DRAFT status, since the Ref Guide in that branch is now considered “live”.
> -- This part of the idea would allow us to more easily backport any docs changes and re-publish the Guide without having to do a new vote, which we would need today. This might be rare, but it is a question that comes up from time-to-time. I feel that if the publication process was easier, we might fix things retroactively more often.
>
> 5. Some tooling would be nice to automate parts of the copy edit process I do today, so it can be run by any committer at any point in the process. This can follow on later. I have a list.
>
> So, that's the idea in a nutshell - thoughts?
>
> [1] Current release process: https://lucene.apache.org/solr/guide/8_1/how-to-contribute.html#ref-guide-publication-process
> [2] Example of DRAFT watermark (it's all CSS, it could look however we want it to): https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-8.x/javadoc/
>
> PS, As for the PDF, I believe there are mixed opinions about it. Some rely on it, others only use it when they need it (portability, easier to search, etc.), others don’t ever look at it. The fact is it’s over 1600 pages, and that’s just really too big. Joel is about to add a significant number of new images as part of a new "visual" guide (see SOLR-13105), which will make it even longer and bigger. Trying to split it to make it smaller would bring in a lot of complexity with how to deal with links between pages that end up in different PDF files (believe me, I've done it before). And finally, it holds us back a little - some things we could do with HTML/JS can't be done in PDF. I’d be fine continuing to produce it, just not as our main artifact. We could have Jenkins push that also to the SVN dist/dev repo where it currently lives.
>
> Cassandra
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Gus Heck
+1 to automate... I never use the PDF I'd be happy to loose it. The page count is the best part of the PDF :).

As far as indexing the ref guide... Cassandra gave a talk on that last year...

On Wed, Sep 18, 2019 at 12:19 PM Alexandre Rafalovitch <[hidden email]> wrote:
+1 on the suggested process. +1 on PDF just being too big, though it
is fun to quote the page count.

An additional idea piggy-backing on this is that in step 4, we could
also automatically build a local example/index that links to the
public version. So, people could search the guide locally and that
would link to the known public URLs for the real HTML.

Regards,
   Alex.

On Wed, 18 Sep 2019 at 12:07, Cassandra Targett <[hidden email]> wrote:
>
> The delays getting the Ref Guides for 8.x releases out have caused me to think a bit about the Ref Guide publication process. It seems clear others aren't able to pick up the process when I can't and I’m sure there are a million individual reasons for that so I don't intend to shame or blame anyone, but a process that relies on a single person in a community our size isn’t a very good one. And, if I think about _why_ we have a process like we have today [1], I’m not sure it makes a ton of sense any longer.
>
> 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 to finally get to the goal of unifying these currently separate processes.
>
> 1. Make the HTML version the “official” version.
> -- What to do with the PDF is TBD after that decision, see below.
>
> 2. Stop voting for the Ref Guide release as a separate VOTE thread.
>
> 3. Jenkins jobs are already created when a release branch is cut. We can change these jobs so they always automatically push the HTML version to the website, although before the version binaries are released the pages would still have a DRAFT watermark across them [2].
> -- 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.
> -- I know other projects have similar Jenkins->publish workflows, but I’m not sure exactly what’s involved in setting it up. Might need to discuss with the Infra team and other changes may be required depending.
> -- The goal, though, is to automate this as much as possible.
>
> 4. When a VOTE has passed, a simple step could be added to the release process to run a Jenkins job to regenerate the HTML pages without the current DRAFT watermark and automatically push them to the production website.
> -- Since we usually leave branch jobs configured-but-disabled for a little bit in case a patch release is necessary, typos or other things fixed “post-release" could be fixed and the Ref Guide Jenkins job would just push new commits to the branch to the live production site.
> -- These updates would be done without the DRAFT status, since the Ref Guide in that branch is now considered “live”.
> -- This part of the idea would allow us to more easily backport any docs changes and re-publish the Guide without having to do a new vote, which we would need today. This might be rare, but it is a question that comes up from time-to-time. I feel that if the publication process was easier, we might fix things retroactively more often.
>
> 5. Some tooling would be nice to automate parts of the copy edit process I do today, so it can be run by any committer at any point in the process. This can follow on later. I have a list.
>
> So, that's the idea in a nutshell - thoughts?
>
> [1] Current release process: https://lucene.apache.org/solr/guide/8_1/how-to-contribute.html#ref-guide-publication-process
> [2] Example of DRAFT watermark (it's all CSS, it could look however we want it to): https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-8.x/javadoc/
>
> PS, As for the PDF, I believe there are mixed opinions about it. Some rely on it, others only use it when they need it (portability, easier to search, etc.), others don’t ever look at it. The fact is it’s over 1600 pages, and that’s just really too big. Joel is about to add a significant number of new images as part of a new "visual" guide (see SOLR-13105), which will make it even longer and bigger. Trying to split it to make it smaller would bring in a lot of complexity with how to deal with links between pages that end up in different PDF files (believe me, I've done it before). And finally, it holds us back a little - some things we could do with HTML/JS can't be done in PDF. I’d be fine continuing to produce it, just not as our main artifact. We could have Jenkins push that also to the SVN dist/dev repo where it currently lives.
>
> Cassandra
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]



--
Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Anshum Gupta
In reply to this post by Cassandra Targett
Thank you Cassandra for all of your effort so far.

I just love that idea. As I said in my previous email (based on my discussion with Cassandra at Activate), having 2 processes, releases, one of which almost the responsibility of one person doesn't sound reasonable.
It would also be great to get more people to vote for both, the code and ref guide instead of just a few people voting for the ref guide.

About updating the ref guide post-release, I think that should be limited to trivial typos, formatting changes only. Anything else would mean that people wouldn't know when something in the documentation changed as it would not come with an announce email.

I don't know much about the ref guide release process so I'm not sure how much effort it would take for this change but I think the effort would certainly be more than worth it in the long term.

On Wed, Sep 18, 2019 at 9:07 AM Cassandra Targett <[hidden email]> wrote:
The delays getting the Ref Guides for 8.x releases out have caused me to think a bit about the Ref Guide publication process. It seems clear others aren't able to pick up the process when I can't and I’m sure there are a million individual reasons for that so I don't intend to shame or blame anyone, but a process that relies on a single person in a community our size isn’t a very good one. And, if I think about _why_ we have a process like we have today [1], I’m not sure it makes a ton of sense any longer.

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 to finally get to the goal of unifying these currently separate processes.

1. Make the HTML version the “official” version.
-- What to do with the PDF is TBD after that decision, see below.

2. Stop voting for the Ref Guide release as a separate VOTE thread.

3. Jenkins jobs are already created when a release branch is cut. We can change these jobs so they always automatically push the HTML version to the website, although before the version binaries are released the pages would still have a DRAFT watermark across them [2].
-- 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.
-- I know other projects have similar Jenkins->publish workflows, but I’m not sure exactly what’s involved in setting it up. Might need to discuss with the Infra team and other changes may be required depending.
-- The goal, though, is to automate this as much as possible.

4. When a VOTE has passed, a simple step could be added to the release process to run a Jenkins job to regenerate the HTML pages without the current DRAFT watermark and automatically push them to the production website.
-- Since we usually leave branch jobs configured-but-disabled for a little bit in case a patch release is necessary, typos or other things fixed “post-release" could be fixed and the Ref Guide Jenkins job would just push new commits to the branch to the live production site.
-- These updates would be done without the DRAFT status, since the Ref Guide in that branch is now considered “live”.
-- This part of the idea would allow us to more easily backport any docs changes and re-publish the Guide without having to do a new vote, which we would need today. This might be rare, but it is a question that comes up from time-to-time. I feel that if the publication process was easier, we might fix things retroactively more often.

5. Some tooling would be nice to automate parts of the copy edit process I do today, so it can be run by any committer at any point in the process. This can follow on later. I have a list.

So, that's the idea in a nutshell - thoughts?

[1] Current release process: https://lucene.apache.org/solr/guide/8_1/how-to-contribute.html#ref-guide-publication-process
[2] Example of DRAFT watermark (it's all CSS, it could look however we want it to): https://builds.apache.org/view/L/view/Lucene/job/Solr-reference-guide-8.x/javadoc/

PS, As for the PDF, I believe there are mixed opinions about it. Some rely on it, others only use it when they need it (portability, easier to search, etc.), others don’t ever look at it. The fact is it’s over 1600 pages, and that’s just really too big. Joel is about to add a significant number of new images as part of a new "visual" guide (see SOLR-13105), which will make it even longer and bigger. Trying to split it to make it smaller would bring in a lot of complexity with how to deal with links between pages that end up in different PDF files (believe me, I've done it before). And finally, it holds us back a little - some things we could do with HTML/JS can't be done in PDF. I’d be fine continuing to produce it, just not as our main artifact. We could have Jenkins push that also to the SVN dist/dev repo where it currently lives.

Cassandra



--
Anshum Gupta
Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Chris Hostetter-3
In reply to this post by Cassandra Targett

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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Jan Høydahl / Cominvent
+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 <[hidden email]>:
>
>
> 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: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Houston Putman
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 <[hidden email]> 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 <[hidden email]>:
>
>
> 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: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Jan Høydahl / Cominvent
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 <[hidden email]>:

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 <[hidden email]> 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 <[hidden email]>:
>
>
> 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: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Chris Hostetter-3

: > 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

: 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,

Yeah, there are a lot of options we could pursue for generating a
"changes" list as part of an automated build process -- but i would
consider this idea a "nice to have" feature that shouldn't block moving
forward.

Given 2 options, I would much rather:
  a) have the ability to quickly/easily "fix" mistakes/ommisions in
"official X.y ref-guide" on our site and have it automatically republish,
w/o it being immediately obvious to users that a page may have changed
between yesterday and today.
      ... over ...
  b) *NOT* being able to re-publish at all just for the sake of users
knowing that the (incorrect) content they are reading is consistent
between yesterday and today.


-Hoss
http://www.lucidworks.com/

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

david.w.smiley@gmail.com
Overall the direction here sounds good to me.  I have/use the PDFs but lately less so since I'm more and more simply searching the asciidoc files within my IDE and viewing them nicely with the IDE plugin simultaneously.

~ David Smiley
Apache Lucene/Solr Search Developer


On Wed, Sep 18, 2019 at 5:48 PM Chris Hostetter <[hidden email]> wrote:

: > 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

: 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,

Yeah, there are a lot of options we could pursue for generating a
"changes" list as part of an automated build process -- but i would
consider this idea a "nice to have" feature that shouldn't block moving
forward.

Given 2 options, I would much rather:
  a) have the ability to quickly/easily "fix" mistakes/ommisions in
"official X.y ref-guide" on our site and have it automatically republish,
w/o it being immediately obvious to users that a page may have changed
between yesterday and today.
      ... over ...
  b) *NOT* being able to re-publish at all just for the sake of users
knowing that the (incorrect) content they are reading is consistent
between yesterday and today.


-Hoss
http://www.lucidworks.com/

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Anshum Gupta
In reply to this post by Chris Hostetter-3
I agree that we should be able to fix mistakes, my only suggestion was that those mistakes not be non-trivial. But the more I think about it, the more I feel convinced about just publishing the updates - however, having a time stamp on when the guide was last updated would be nice to have. Anything else would require much more effort and I'm not sure it's worth it.

On Wed, Sep 18, 2019 at 2:48 PM Chris Hostetter <[hidden email]> wrote:

: > 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

: 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,

Yeah, there are a lot of options we could pursue for generating a
"changes" list as part of an automated build process -- but i would
consider this idea a "nice to have" feature that shouldn't block moving
forward.

Given 2 options, I would much rather:
  a) have the ability to quickly/easily "fix" mistakes/ommisions in
"official X.y ref-guide" on our site and have it automatically republish,
w/o it being immediately obvious to users that a page may have changed
between yesterday and today.
      ... over ...
  b) *NOT* being able to re-publish at all just for the sake of users
knowing that the (incorrect) content they are reading is consistent
between yesterday and today.


-Hoss
http://www.lucidworks.com/

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]



--
Anshum Gupta
Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Cassandra Targett
The pages do already have a “Site last generated” date on them at the bottom. It’s specifically worded that way for a reason.

We actually wanted the date the .adoc file was last updated to be in the footer too, but the problem has always been that a static site generator always regenerates all pages every time - so every single page, edited or not, always has the same exact date on it.

And, our build works by copying everything under `solr/solr-ref-guide/src` to `solr/build`, so every file really has a create date and last updated date that are always the date you do the build. Basically, the files you see and work with are not actually the same files that get built - we build from copies that are made at build-time.

(That’s all why it says “Site last generated” instead of “Last updated”.)

I’m not saying there’s no way to add a last updated date for the underlying file, it’s just not obvious how to do it so we skipped it.

No problem, though, adding a link to Github - that’s actually kind of a different thing and I’m pretty sure we could do that right now.

Cassandra
On Sep 19, 2019, 7:07 AM -0500, Anshum Gupta <[hidden email]>, wrote:
I agree that we should be able to fix mistakes, my only suggestion was that those mistakes not be non-trivial. But the more I think about it, the more I feel convinced about just publishing the updates - however, having a time stamp on when the guide was last updated would be nice to have. Anything else would require much more effort and I'm not sure it's worth it.

On Wed, Sep 18, 2019 at 2:48 PM Chris Hostetter <[hidden email]> wrote:

: > 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

: 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,

Yeah, there are a lot of options we could pursue for generating a
"changes" list as part of an automated build process -- but i would
consider this idea a "nice to have" feature that shouldn't block moving
forward.

Given 2 options, I would much rather:
  a) have the ability to quickly/easily "fix" mistakes/ommisions in
"official X.y ref-guide" on our site and have it automatically republish,
w/o it being immediately obvious to users that a page may have changed
between yesterday and today.
      ... over ...
  b) *NOT* being able to re-publish at all just for the sake of users
knowing that the (incorrect) content they are reading is consistent
between yesterday and today.


-Hoss
http://www.lucidworks.com/

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]



--
Anshum Gupta
Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Noble Paul നോബിള്‍  नोब्ळ्
First of all a big thanks to Cassandra to help coordinate and build
our ref guide to make it professional. It really used to be pathetic
before you took over

. Yes we need to avoid "creating work" . There should be no need for a
ref guide release.

+1 for your plan

On Thu, Sep 19, 2019 at 11:57 PM Cassandra Targett
<[hidden email]> wrote:

>
> The pages do already have a “Site last generated” date on them at the bottom. It’s specifically worded that way for a reason.
>
> We actually wanted the date the .adoc file was last updated to be in the footer too, but the problem has always been that a static site generator always regenerates all pages every time - so every single page, edited or not, always has the same exact date on it.
>
> And, our build works by copying everything under `solr/solr-ref-guide/src` to `solr/build`, so every file really has a create date and last updated date that are always the date you do the build. Basically, the files you see and work with are not actually the same files that get built - we build from copies that are made at build-time.
>
> (That’s all why it says “Site last generated” instead of “Last updated”.)
>
> I’m not saying there’s no way to add a last updated date for the underlying file, it’s just not obvious how to do it so we skipped it.
>
> No problem, though, adding a link to Github - that’s actually kind of a different thing and I’m pretty sure we could do that right now.
>
> Cassandra
> On Sep 19, 2019, 7:07 AM -0500, Anshum Gupta <[hidden email]>, wrote:
>
> I agree that we should be able to fix mistakes, my only suggestion was that those mistakes not be non-trivial. But the more I think about it, the more I feel convinced about just publishing the updates - however, having a time stamp on when the guide was last updated would be nice to have. Anything else would require much more effort and I'm not sure it's worth it.
>
> On Wed, Sep 18, 2019 at 2:48 PM Chris Hostetter <[hidden email]> wrote:
>>
>>
>> : > 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
>>
>> : 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,
>>
>> Yeah, there are a lot of options we could pursue for generating a
>> "changes" list as part of an automated build process -- but i would
>> consider this idea a "nice to have" feature that shouldn't block moving
>> forward.
>>
>> Given 2 options, I would much rather:
>>   a) have the ability to quickly/easily "fix" mistakes/ommisions in
>> "official X.y ref-guide" on our site and have it automatically republish,
>> w/o it being immediately obvious to users that a page may have changed
>> between yesterday and today.
>>       ... over ...
>>   b) *NOT* being able to re-publish at all just for the sake of users
>> knowing that the (incorrect) content they are reading is consistent
>> between yesterday and today.
>>
>>
>> -Hoss
>> http://www.lucidworks.com/
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>
>
> --
> Anshum Gupta



--
-----------------------------------------------------
Noble Paul

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Cassandra Targett
Thanks everyone, by the way, for the encouragement and feedback here.

For next steps, how do folks feel about making the change to stop voting on the PDF *now*? Or, I guess, retroactively for 8.2 since that’s not out yet. I could push the HTML and make a PDF but announce to the list that from 8.2 forward we consider the HTML the main Ref Guide and the PDF is “for convenience” (and explain the thinking behind it).

If we want a VOTE on this policy change, I can do that - I feel like we have consensus without it, but we could be more formal about it if folks prefer.

For 8.3 we'll see what we can get automated there, but if it’s not ready I’ll just do it manually once the RC is out.

I’ll file a Jira for some of the changes I’ll make to the docs for the process, etc., and another one for automation ideas.

Cassandra
On Sep 19, 2019, 2:53 PM -0500, Noble Paul <[hidden email]>, wrote:
First of all a big thanks to Cassandra to help coordinate and build
our ref guide to make it professional. It really used to be pathetic
before you took over

. Yes we need to avoid "creating work" . There should be no need for a
ref guide release.

+1 for your plan

On Thu, Sep 19, 2019 at 11:57 PM Cassandra Targett
<[hidden email]> wrote:

The pages do already have a “Site last generated” date on them at the bottom. It’s specifically worded that way for a reason.

We actually wanted the date the .adoc file was last updated to be in the footer too, but the problem has always been that a static site generator always regenerates all pages every time - so every single page, edited or not, always has the same exact date on it.

And, our build works by copying everything under `solr/solr-ref-guide/src` to `solr/build`, so every file really has a create date and last updated date that are always the date you do the build. Basically, the files you see and work with are not actually the same files that get built - we build from copies that are made at build-time.

(That’s all why it says “Site last generated” instead of “Last updated”.)

I’m not saying there’s no way to add a last updated date for the underlying file, it’s just not obvious how to do it so we skipped it.

No problem, though, adding a link to Github - that’s actually kind of a different thing and I’m pretty sure we could do that right now.

Cassandra
On Sep 19, 2019, 7:07 AM -0500, Anshum Gupta <[hidden email]>, wrote:

I agree that we should be able to fix mistakes, my only suggestion was that those mistakes not be non-trivial. But the more I think about it, the more I feel convinced about just publishing the updates - however, having a time stamp on when the guide was last updated would be nice to have. Anything else would require much more effort and I'm not sure it's worth it.

On Wed, Sep 18, 2019 at 2:48 PM Chris Hostetter <[hidden email]> wrote:


: > 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

: 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,

Yeah, there are a lot of options we could pursue for generating a
"changes" list as part of an automated build process -- but i would
consider this idea a "nice to have" feature that shouldn't block moving
forward.

Given 2 options, I would much rather:
a) have the ability to quickly/easily "fix" mistakes/ommisions in
"official X.y ref-guide" on our site and have it automatically republish,
w/o it being immediately obvious to users that a page may have changed
between yesterday and today.
... over ...
b) *NOT* being able to re-publish at all just for the sake of users
knowing that the (incorrect) content they are reading is consistent
between yesterday and today.


-Hoss
http://www.lucidworks.com/

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]



--
Anshum Gupta



--
-----------------------------------------------------
Noble Paul

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Rethinking how we publish the Solr Ref Guide

Jason Gerlowski
+1.  That all sounds good to me.  Excited to see some streamlining here.

On Fri, Sep 20, 2019 at 3:46 PM Cassandra Targett <[hidden email]> wrote:

>
> Thanks everyone, by the way, for the encouragement and feedback here.
>
> For next steps, how do folks feel about making the change to stop voting on the PDF *now*? Or, I guess, retroactively for 8.2 since that’s not out yet. I could push the HTML and make a PDF but announce to the list that from 8.2 forward we consider the HTML the main Ref Guide and the PDF is “for convenience” (and explain the thinking behind it).
>
> If we want a VOTE on this policy change, I can do that - I feel like we have consensus without it, but we could be more formal about it if folks prefer.
>
> For 8.3 we'll see what we can get automated there, but if it’s not ready I’ll just do it manually once the RC is out.
>
> I’ll file a Jira for some of the changes I’ll make to the docs for the process, etc., and another one for automation ideas.
>
> Cassandra
> On Sep 19, 2019, 2:53 PM -0500, Noble Paul <[hidden email]>, wrote:
>
> First of all a big thanks to Cassandra to help coordinate and build
> our ref guide to make it professional. It really used to be pathetic
> before you took over
>
> . Yes we need to avoid "creating work" . There should be no need for a
> ref guide release.
>
> +1 for your plan
>
> On Thu, Sep 19, 2019 at 11:57 PM Cassandra Targett
> <[hidden email]> wrote:
>
>
> The pages do already have a “Site last generated” date on them at the bottom. It’s specifically worded that way for a reason.
>
> We actually wanted the date the .adoc file was last updated to be in the footer too, but the problem has always been that a static site generator always regenerates all pages every time - so every single page, edited or not, always has the same exact date on it.
>
> And, our build works by copying everything under `solr/solr-ref-guide/src` to `solr/build`, so every file really has a create date and last updated date that are always the date you do the build. Basically, the files you see and work with are not actually the same files that get built - we build from copies that are made at build-time.
>
> (That’s all why it says “Site last generated” instead of “Last updated”.)
>
> I’m not saying there’s no way to add a last updated date for the underlying file, it’s just not obvious how to do it so we skipped it.
>
> No problem, though, adding a link to Github - that’s actually kind of a different thing and I’m pretty sure we could do that right now.
>
> Cassandra
> On Sep 19, 2019, 7:07 AM -0500, Anshum Gupta <[hidden email]>, wrote:
>
> I agree that we should be able to fix mistakes, my only suggestion was that those mistakes not be non-trivial. But the more I think about it, the more I feel convinced about just publishing the updates - however, having a time stamp on when the guide was last updated would be nice to have. Anything else would require much more effort and I'm not sure it's worth it.
>
> On Wed, Sep 18, 2019 at 2:48 PM Chris Hostetter <[hidden email]> wrote:
>
>
>
> : > 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
>
> : 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,
>
> Yeah, there are a lot of options we could pursue for generating a
> "changes" list as part of an automated build process -- but i would
> consider this idea a "nice to have" feature that shouldn't block moving
> forward.
>
> Given 2 options, I would much rather:
> a) have the ability to quickly/easily "fix" mistakes/ommisions in
> "official X.y ref-guide" on our site and have it automatically republish,
> w/o it being immediately obvious to users that a page may have changed
> between yesterday and today.
> ... over ...
> b) *NOT* being able to re-publish at all just for the sake of users
> knowing that the (incorrect) content they are reading is consistent
> between yesterday and today.
>
>
> -Hoss
> http://www.lucidworks.com/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
>
> --
> Anshum Gupta
>
>
>
>
> --
> -----------------------------------------------------
> Noble Paul
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]