You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Cassandra Targett <ca...@gmail.com> on 2019/09/18 16:06:37 UTC
Rethinking how we publish the Solr Ref Guide
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
Re: Rethinking how we publish the Solr Ref Guide
Posted by Anshum Gupta <an...@anshumgupta.net>.
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 <ca...@gmail.com>
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
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gézapeti <ge...@gmail.com>.
Thanks for the help! The link was an internal documentation I assumed it
was correct. I've updated it in our wiki page.
On Mon, Oct 28, 2019 at 7:57 PM Cassandra Targett <ca...@gmail.com>
wrote:
> Yes, it does need to be updated. I was waiting to do that until I informed
> the user list about the change to not publish a PDF any longer which I’m
> ready to send now, so I’ll also fix the redirect link.
>
> Cassandra
> On Oct 28, 2019, 12:23 PM -0500, Gus Heck <gu...@gmail.com>, wrote:
>
> Ah yes I assumed that the original link had come from a good source...
> OTOH
> https://lucene.apache.org/solr/guide/field-types-included-with-solr.html still
> needs to be updated to point to 8_2 I think.
>
> On Mon, Oct 28, 2019 at 1:01 PM Chris Hostetter <ho...@fucit.org>
> wrote:
>
>>
>> : The redirection is wrong, if you remove "latest" from the urls with 8_1
>> in
>>
>> The "redirection" rules appear to be working as designed -- but AFAIK they
>> were never designed with any idea of having a "latest/" path.
>>
>> the Latest URL has no is just the page name w/o a version number, not the
>> page name prefixed with "latest/".
>>
>> Specifically this is suppose to be the "latest" URL for the page in
>> question...
>>
>> https://lucene.apache.org/solr/guide/field-types-included-with-solr.html
>>
>> : > I was trying to access
>> : >
>> https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
>>
>> ...where did you find that link?
>>
>> I'm pretty sure the place that linked to that URL is the place that has a
>> mistake.
>>
>>
>>
>> -Hoss
>> http://www.lucidworks.com/
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
>
> --
> http://www.needhamsoftware.com (work)
> http://www.the111shift.com (play)
>
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Cassandra Targett <ca...@gmail.com>.
Yes, it does need to be updated. I was waiting to do that until I informed the user list about the change to not publish a PDF any longer which I’m ready to send now, so I’ll also fix the redirect link.
Cassandra
On Oct 28, 2019, 12:23 PM -0500, Gus Heck <gu...@gmail.com>, wrote:
> Ah yes I assumed that the original link had come from a good source... OTOH https://lucene.apache.org/solr/guide/field-types-included-with-solr.html still needs to be updated to point to 8_2 I think.
>
> > On Mon, Oct 28, 2019 at 1:01 PM Chris Hostetter <ho...@fucit.org> wrote:
> > >
> > > : The redirection is wrong, if you remove "latest" from the urls with 8_1 in
> > >
> > > The "redirection" rules appear to be working as designed -- but AFAIK they
> > > were never designed with any idea of having a "latest/" path.
> > >
> > > the Latest URL has no is just the page name w/o a version number, not the
> > > page name prefixed with "latest/".
> > >
> > > Specifically this is suppose to be the "latest" URL for the page in
> > > question...
> > >
> > > https://lucene.apache.org/solr/guide/field-types-included-with-solr.html
> > >
> > > : > I was trying to access
> > > : > https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
> > >
> > > ...where did you find that link?
> > >
> > > I'm pretty sure the place that linked to that URL is the place that has a
> > > mistake.
> > >
> > >
> > >
> > > -Hoss
> > > http://www.lucidworks.com/
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> > > For additional commands, e-mail: dev-help@lucene.apache.org
> > >
>
>
> --
> http://www.needhamsoftware.com (work)
> http://www.the111shift.com (play)
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gus Heck <gu...@gmail.com>.
Ah yes I assumed that the original link had come from a good source... OTOH
https://lucene.apache.org/solr/guide/field-types-included-with-solr.html still
needs to be updated to point to 8_2 I think.
On Mon, Oct 28, 2019 at 1:01 PM Chris Hostetter <ho...@fucit.org>
wrote:
>
> : The redirection is wrong, if you remove "latest" from the urls with 8_1
> in
>
> The "redirection" rules appear to be working as designed -- but AFAIK they
> were never designed with any idea of having a "latest/" path.
>
> the Latest URL has no is just the page name w/o a version number, not the
> page name prefixed with "latest/".
>
> Specifically this is suppose to be the "latest" URL for the page in
> question...
>
> https://lucene.apache.org/solr/guide/field-types-included-with-solr.html
>
> : > I was trying to access
> : >
> https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
>
> ...where did you find that link?
>
> I'm pretty sure the place that linked to that URL is the place that has a
> mistake.
>
>
>
> -Hoss
> http://www.lucidworks.com/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Rethinking how we publish the Solr Ref Guide
Posted by Chris Hostetter <ho...@fucit.org>.
: The redirection is wrong, if you remove "latest" from the urls with 8_1 in
The "redirection" rules appear to be working as designed -- but AFAIK they
were never designed with any idea of having a "latest/" path.
the Latest URL has no is just the page name w/o a version number, not the
page name prefixed with "latest/".
Specifically this is suppose to be the "latest" URL for the page in
question...
https://lucene.apache.org/solr/guide/field-types-included-with-solr.html
: > I was trying to access
: > https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
...where did you find that link?
I'm pretty sure the place that linked to that URL is the place that has a
mistake.
-Hoss
http://www.lucidworks.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gus Heck <gu...@gmail.com>.
The redirection is wrong, if you remove "latest" from the urls with 8_1 in
them it looks like you get the right page. Also, 8_2 is the latest now so
these are also out of date I think.
On Mon, Oct 28, 2019 at 10:24 AM Gézapeti <ge...@gmail.com> wrote:
> Hi everyone,
>
> I was trying to access
> https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
> and it got redirected to
> https://lucene.apache.org/solr/guide/8_1/latest/field-types-included-with-solr.html
> which is a 404.
> I've tested https://lucene.apache.org/solr/guide/latest/ and it also
> redirects to https://lucene.apache.org/solr/guide/8_1/latest/
> I could not find the reference for this in the ref-guide project.
> Can someone fix it or point me in the right direction to fix the issue?
> Thanks
> gp
>
> On Wed, Oct 23, 2019 at 7:53 PM Cassandra Targett <ca...@gmail.com>
> wrote:
>
>> FYI, bumping this - I’m about to send a mail to the user list explaining
>> why we’ve stopped releasing the PDF.
>>
>> I think I said originally we’d publish the 8.2 PDF, but I’ve changed my
>> mind on that and edited the Ref Guide landing page to include 8.2 and
>> indicate it is HTML only starting with 8.2.
>>
>> If there is an outcry in the community about the change, we can discuss
>> other options depending on the feedback.
>>
>> Cassandra
>> On Sep 23, 2019, 9:54 AM -0500, Jason Gerlowski <ge...@gmail.com>,
>> wrote:
>>
>> +1. That all sounds good to me. Excited to see some streamlining here.
>>
>> On Fri, Sep 20, 2019 at 3:46 PM Cassandra Targett <ca...@gmail.com>
>> 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 <no...@gmail.com>, 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
>> <ca...@gmail.com> 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 <an...@anshumgupta.net>,
>> 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 <ho...@fucit.org>
>> 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: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
>>
>> --
>> Anshum Gupta
>>
>>
>>
>>
>> --
>> -----------------------------------------------------
>> Noble Paul
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gézapeti <ge...@gmail.com>.
Hi everyone,
I was trying to access
https://lucene.apache.org/solr/guide/latest/field-types-included-with-solr.html
and it got redirected to
https://lucene.apache.org/solr/guide/8_1/latest/field-types-included-with-solr.html
which is a 404.
I've tested https://lucene.apache.org/solr/guide/latest/ and it also
redirects to https://lucene.apache.org/solr/guide/8_1/latest/
I could not find the reference for this in the ref-guide project.
Can someone fix it or point me in the right direction to fix the issue?
Thanks
gp
On Wed, Oct 23, 2019 at 7:53 PM Cassandra Targett <ca...@gmail.com>
wrote:
> FYI, bumping this - I’m about to send a mail to the user list explaining
> why we’ve stopped releasing the PDF.
>
> I think I said originally we’d publish the 8.2 PDF, but I’ve changed my
> mind on that and edited the Ref Guide landing page to include 8.2 and
> indicate it is HTML only starting with 8.2.
>
> If there is an outcry in the community about the change, we can discuss
> other options depending on the feedback.
>
> Cassandra
> On Sep 23, 2019, 9:54 AM -0500, Jason Gerlowski <ge...@gmail.com>,
> wrote:
>
> +1. That all sounds good to me. Excited to see some streamlining here.
>
> On Fri, Sep 20, 2019 at 3:46 PM Cassandra Targett <ca...@gmail.com>
> 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 <no...@gmail.com>, 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
> <ca...@gmail.com> 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 <an...@anshumgupta.net>,
> 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 <ho...@fucit.org>
> 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: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
>
> --
> Anshum Gupta
>
>
>
>
> --
> -----------------------------------------------------
> Noble Paul
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Cassandra Targett <ca...@gmail.com>.
FYI, bumping this - I’m about to send a mail to the user list explaining why we’ve stopped releasing the PDF.
I think I said originally we’d publish the 8.2 PDF, but I’ve changed my mind on that and edited the Ref Guide landing page to include 8.2 and indicate it is HTML only starting with 8.2.
If there is an outcry in the community about the change, we can discuss other options depending on the feedback.
Cassandra
On Sep 23, 2019, 9:54 AM -0500, Jason Gerlowski <ge...@gmail.com>, wrote:
> +1. That all sounds good to me. Excited to see some streamlining here.
>
> On Fri, Sep 20, 2019 at 3:46 PM Cassandra Targett <ca...@gmail.com> 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 <no...@gmail.com>, 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
> > <ca...@gmail.com> 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 <an...@anshumgupta.net>, 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 <ho...@fucit.org> 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: dev-unsubscribe@lucene.apache.org
> > For additional commands, e-mail: dev-help@lucene.apache.org
> >
> >
> >
> > --
> > Anshum Gupta
> >
> >
> >
> >
> > --
> > -----------------------------------------------------
> > Noble Paul
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> > For additional commands, e-mail: dev-help@lucene.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Jason Gerlowski <ge...@gmail.com>.
+1. That all sounds good to me. Excited to see some streamlining here.
On Fri, Sep 20, 2019 at 3:46 PM Cassandra Targett <ca...@gmail.com> 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 <no...@gmail.com>, 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
> <ca...@gmail.com> 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 <an...@anshumgupta.net>, 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 <ho...@fucit.org> 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: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
>
> --
> Anshum Gupta
>
>
>
>
> --
> -----------------------------------------------------
> Noble Paul
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Rethinking how we publish the Solr Ref Guide
Posted by Cassandra Targett <ca...@gmail.com>.
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 <no...@gmail.com>, 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
> <ca...@gmail.com> 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 <an...@anshumgupta.net>, 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 <ho...@fucit.org> 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: dev-unsubscribe@lucene.apache.org
> > > For additional commands, e-mail: dev-help@lucene.apache.org
> > >
> >
> >
> > --
> > Anshum Gupta
>
>
>
> --
> -----------------------------------------------------
> Noble Paul
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Noble Paul <no...@gmail.com>.
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
<ca...@gmail.com> 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 <an...@anshumgupta.net>, 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 <ho...@fucit.org> 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: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>
>
> --
> Anshum Gupta
--
-----------------------------------------------------
Noble Paul
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Rethinking how we publish the Solr Ref Guide
Posted by Cassandra Targett <ca...@gmail.com>.
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 <an...@anshumgupta.net>, 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 <ho...@fucit.org> 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: dev-unsubscribe@lucene.apache.org
> > > For additional commands, e-mail: dev-help@lucene.apache.org
> > >
>
>
> --
> Anshum Gupta
Re: Rethinking how we publish the Solr Ref Guide
Posted by Anshum Gupta <an...@anshumgupta.net>.
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 <ho...@fucit.org>
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: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
--
Anshum Gupta
Re: Rethinking how we publish the Solr Ref Guide
Posted by David Smiley <da...@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
http://www.linkedin.com/in/davidwsmiley
On Wed, Sep 18, 2019 at 5:48 PM Chris Hostetter <ho...@fucit.org>
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: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Chris Hostetter <ho...@fucit.org>.
: > 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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Rethinking how we publish the Solr Ref Guide
Posted by Jan Høydahl <ja...@cominvent.com>.
> 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 <ho...@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.asf@cominvent.com <ma...@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_lucene@fucit.org <ma...@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-unsubscribe@lucene.apache.org <ma...@lucene.apache.org>
> > For additional commands, e-mail: dev-help@lucene.apache.org <ma...@lucene.apache.org>
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org <ma...@lucene.apache.org>
> For additional commands, e-mail: dev-help@lucene.apache.org <ma...@lucene.apache.org>
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Houston Putman <ho...@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 <ja...@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_lucene@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-unsubscribe@lucene.apache.org
> > For additional commands, e-mail: dev-help@lucene.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
Re: Rethinking how we publish the Solr Ref Guide
Posted by Jan Høydahl <ja...@cominvent.com>.
+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 <ho...@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-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Rethinking how we publish the Solr Ref Guide
Posted by Chris Hostetter <ho...@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-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: Rethinking how we publish the Solr Ref Guide
Posted by Gus Heck <gu...@gmail.com>.
+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...
https://www.youtube.com/watch?v=DixlnxAk08s&list=PLU6n9Voqu_1HW8-VavVMa9lP8-oF8Oh5t&index=14
On Wed, Sep 18, 2019 at 12:19 PM Alexandre Rafalovitch <ar...@gmail.com>
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 <ca...@gmail.com>
> 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: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
--
http://www.needhamsoftware.com (work)
http://www.the111shift.com (play)
Re: Rethinking how we publish the Solr Ref Guide
Posted by Alexandre Rafalovitch <ar...@gmail.com>.
+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 <ca...@gmail.com> 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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org