Re: Proposal to Move Solr Ref Guide off Confluence

[David Smiley]

On Mon, Aug 22, 2016 at 9:46 AM Jan Høydahl  wrote:

> Pull requests for docs is a great plus so more people can contribute. The
> online version-specific docs can then have a link below each page
> encouraging people to contribute through PR to version-branch or by comment
> system.
>
> An issue with only maintaining the next-release branch is that docs on
> master will get out of date. But that is perhaps not a problem since there
> will not be an online HTML version of master? Anyway, with a merge-forward
> strategy, we could e.g. merge to master after each point release on 6.x, to
> avoid the gap becoming too large over time.
>

Yup; +1!  I think that's how we should do it.

-- 
Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker
LinkedIn: http://linkedin.com/in/davidwsmiley | Book:
http://www.solrenterprisesearchserver.com

Re: Proposal to Move Solr Ref Guide off Confluence

[Jan Høydahl]

Pull requests for docs is a great plus so more people can contribute. The 
online version-specific docs can then have a link below each page encouraging 
people to contribute through PR to version-branch or by comment system.

An issue with only maintaining the next-release branch is that docs on master 
will get out of date. But that is perhaps not a problem since there will not be 
an online HTML version of master? Anyway, with a merge-forward strategy, we 
could e.g. merge to master after each point release on 6.x, to avoid the gap 
becoming too large over time.

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com

> 19. aug. 2016 kl. 19.48 skrev Tomás Fernández Löbbe :
> 
> Thanks for taking time for looking at these options Casandra. I specially 
> agree with the third of the painful points you mentioned, the fact that we 
> can't maintain online documentation for different versions. I like that we 
> have a released PDF version for every minor version, but 99.9% of the time 
> I'm online and I just want to go to the online version and browse the HTML 
> docs, it's a pain that I can't just choose my version there. 
> I also agree 100% with Doug's point, that we should make sure that links to 
> the current documentation pages are correctly forwarded to the new docs.
> Accepting pull requests would also be nice, many of the comments in 
> Confluence are "there is a typo in…" or "X section is missing parameter Y", I 
> bet many of those comments will become PRs if we offered the option (don't 
> know if this can be handled without Jira)
> 
> About branching and merging, we currently write docs for the next version 
> (minor usually), very few things are written for master only, and they 
> currently live in a separate Confluence area that's not released. One option 
> would be keep doing this, which will prevent many merges (at the cost of 
> making it more difficult to release docs for new major versions).
> 
> in general, +1 for the idea.
> 
> Tomás
> 
> On Fri, Aug 19, 2016 at 10:23 AM, Chris Hostetter  > wrote:
> 
> : I am not against having multiple documentation branches -- I am *for*
> : that.  I am against emulating our current source code practice of needing
> : to commit twice (two branches) for most things.  I think that should be the
> : exception, not the rule.  Only during a new dot-zero release would we be
> : compelled to merge forward the changes from the previous branch.
> 
> To be very clear, my point was that by moving out of confluence and to an
> asciidoc based system kept in git, we know have the *choice* to
> maintain/backport documentation for multiple versions, and an easy way to
> backport changes.
> 
> This is not even a viable *option* for us to consider with confluence.
> 
> if/how/when to backport/forward-port documentation is a policy question we
> can decide at a later date -- the hypothetical example i gave was just one
> that assumed we'd want to keep docs in sync with code --  The main take
> away was to point out that we can now make that decision for ourselves if
> we migrat out of confluence.
> 
> 
> 
> -Hoss
> http://www.lucidworks.com/ 
> 
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org 
> 
> For additional commands, e-mail: dev-h...@lucene.apache.org 
> 
> 
> 

Re: Proposal to Move Solr Ref Guide off Confluence

[Tomás Fernández Löbbe]

Thanks for taking time for looking at these options Casandra. I specially
agree with the third of the painful points you mentioned, the fact that we
can't maintain online documentation for different versions. I like that we
have a released PDF version for every minor version, but 99.9% of the time
I'm online and I just want to go to the online version and browse the HTML
docs, it's a pain that I can't just choose my version there.
I also agree 100% with Doug's point, that we should make sure that links to
the current documentation pages are correctly forwarded to the new docs.
Accepting pull requests would also be nice, many of the comments in
Confluence are "there is a typo in…" or "X section is missing parameter Y",
I bet many of those comments will become PRs if we offered the option
(don't know if this can be handled without Jira)

About branching and merging, we currently write docs for the next version
(minor usually), very few things are written for master only, and they
currently live in a separate Confluence area that's not released. One
option would be keep doing this, which will prevent many merges (at the
cost of making it more difficult to release docs for new major versions).

in general, +1 for the idea.

Tomás

On Fri, Aug 19, 2016 at 10:23 AM, Chris Hostetter 
wrote:

>
> : I am not against having multiple documentation branches -- I am *for*
> : that.  I am against emulating our current source code practice of needing
> : to commit twice (two branches) for most things.  I think that should be
> the
> : exception, not the rule.  Only during a new dot-zero release would we be
> : compelled to merge forward the changes from the previous branch.
>
> To be very clear, my point was that by moving out of confluence and to an
> asciidoc based system kept in git, we know have the *choice* to
> maintain/backport documentation for multiple versions, and an easy way to
> backport changes.
>
> This is not even a viable *option* for us to consider with confluence.
>
> if/how/when to backport/forward-port documentation is a policy question we
> can decide at a later date -- the hypothetical example i gave was just one
> that assumed we'd want to keep docs in sync with code --  The main take
> away was to point out that we can now make that decision for ourselves if
> we migrat out of confluence.
>
>
>
> -Hoss
> http://www.lucidworks.com/
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: dev-h...@lucene.apache.org
>
>

Re: Proposal to Move Solr Ref Guide off Confluence

[Shawn Heisey]

On 8/19/2016 11:23 AM, Chris Hostetter wrote:
> To be very clear, my point was that by moving out of confluence and to an 
> asciidoc based system kept in git, we know have the *choice* to 
> maintain/backport documentation for multiple versions, and an easy way to 
> backport changes.
>
> This is not even a viable *option* for us to consider with confluence.

+1 to the move.  I haven't got any idea how asciidoc works, but I trust
the judgement of those who think it's a viable option.  Having the
documentation in version control opens up a lot of possibilities.

Questions about how to manage the workflow can be decidedlater, in the
implementation phase, when/if the immediate proposal is approved.  I
have one or two ideas to discuss.

Thanks,
Shawn


-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[Chris Hostetter]

: I am not against having multiple documentation branches -- I am *for*
: that.  I am against emulating our current source code practice of needing
: to commit twice (two branches) for most things.  I think that should be the
: exception, not the rule.  Only during a new dot-zero release would we be
: compelled to merge forward the changes from the previous branch.

To be very clear, my point was that by moving out of confluence and to an 
asciidoc based system kept in git, we know have the *choice* to 
maintain/backport documentation for multiple versions, and an easy way to 
backport changes.

This is not even a viable *option* for us to consider with confluence.

if/how/when to backport/forward-port documentation is a policy question we 
can decide at a later date -- the hypothetical example i gave was just one 
that assumed we'd want to keep docs in sync with code --  The main take 
away was to point out that we can now make that decision for ourselves if 
we migrat out of confluence.



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

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[David Smiley]

I am not against having multiple documentation branches -- I am *for*
that.  I am against emulating our current source code practice of needing
to commit twice (two branches) for most things.  I think that should be the
exception, not the rule.  Only during a new dot-zero release would we be
compelled to merge forward the changes from the previous branch.

~ David

On Fri, Aug 19, 2016 at 11:05 AM Cassandra Targett 
wrote:

> On Thu, Aug 18, 2016 at 8:48 PM, David Smiley 
> wrote:
>
> > Ugh!  I think it's a PITA that we basically always back-port all commits
> to
> > another branch, and the prospect of having to do this to documentation as
> > well will add a large barrier to editing the docs.  I propose an
> alternative
> > way:  Like having everything go into a 6x branch and then have the 7x
> branch
> > be only for things unique to 7x?  From time to time and definitely when
> 7.0
> > arrives, we then merge 6x into 7x.  Some things we will need to remember
> to
> > remove from 7x, and there will be merge conflicts, but I think the
> > down-sides there far outweigh the lower barrier to editing the
> > documentation.
> >
>
> I'm not totally following your idea about the branches, but I think
> we'd want to use some discretion about what types of changes need to
> be backported, and also when an older version is re-published. If you
> fix one typo do you need to build the whole Ref Guide again? Seems
> overkill. If a page has had a typo for 3 releases, do you need to
> backport a small change to all those branches?
>
> We should agree on some guidelines around this. We can use existing
> conventions to start - if you found a typo in the javadocs and chose
> to fix it, would you backport it to all the active branches? It seems
> to me that people generally don't do that, and I think we could apply
> the same principle here. The key point being we could agree to this
> and write it down.
>
> > Make no mistake, for all the numerous benefits of moving to a
> source-control
> > based editing, it will become harder to make small edits/fixes to the
> docs.
> > In under 15 seconds I can fix any trivial typo in Confluence.  We need to
> > recognize this with eyes wide open before choosing the trade-offs.  I
> still
> > think it will be a worthwhile trade-off *if* we strive to make editing
> the
> > docs in the new system as easy as possible.  Needing to usually commit to
> > two branches is a *huge* blow to that.  As it is, apparently I need to go
> > finding some asciidoc IDE that I didn't need yet.  Not for typo fixes of
> > course, but any way my browser isn't enough any more.
> >
>
> You don't need an IDE. The tools that have been mentioned are only to
> preview an Asciidoc page as HTML, as an aid to see your changes as you
> make them and not a requirement. Asciidoc is just like Markdown -
> mostly the same syntaxes, and the changes are mostly additions to
> extend the capabilities of Markdown. But it's a markup language, so
> for some edits it's easier to see what it might look like online.
>
> (By the way, the paragraph I just wrote is 100% valid Asciidoc, no IDE
> required.)
>
> I definitely hear your point about it being really simple to fix small
> things today. There is no perfect solution, everything has one
> drawback or another. Today you don't have the problem of having to
> backport it, because we have no way of having docs for different
> versions. If we want maintainable docs for other versions - the idea
> came up again a few months ago when the idea of a Solr 5.6 was
> initially raised - we'll have to address the issue of how to maintain
> those prior versions.
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: dev-h...@lucene.apache.org
>
> --
Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker
LinkedIn: http://linkedin.com/in/davidwsmiley | Book:
http://www.solrenterprisesearchserver.com

Re: Proposal to Move Solr Ref Guide off Confluence

[Cassandra Targett]

On Thu, Aug 18, 2016 at 10:38 PM, Erick Erickson
 wrote:
>
> The other question I have is how to find the file I want to edit. I'm
> taking it on faith that there's a way to find a particular asciidoc
> file without resorting to a recursive grep, but if not I can cope with
> that since every damn major edit I've wanted to do on Confluence has
> caused a dangerous rise in my blood pressure.
>

To start, all the files are going to have the same names as their
online counterparts, so it will be easy.

Asciidoc allows for one page to include another page (or even parts of
another page) and in the future we might choose to reorganize things
to take advantage of that. Then it would get a little more
complicated, but if that happens, we'll have to consider your concern
and see if there are easy ways to mitigate potential confusion.

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[Cassandra Targett]

On Thu, Aug 18, 2016 at 8:48 PM, David Smiley  wrote:

> Ugh!  I think it's a PITA that we basically always back-port all commits to
> another branch, and the prospect of having to do this to documentation as
> well will add a large barrier to editing the docs.  I propose an alternative
> way:  Like having everything go into a 6x branch and then have the 7x branch
> be only for things unique to 7x?  From time to time and definitely when 7.0
> arrives, we then merge 6x into 7x.  Some things we will need to remember to
> remove from 7x, and there will be merge conflicts, but I think the
> down-sides there far outweigh the lower barrier to editing the
> documentation.
>

I'm not totally following your idea about the branches, but I think
we'd want to use some discretion about what types of changes need to
be backported, and also when an older version is re-published. If you
fix one typo do you need to build the whole Ref Guide again? Seems
overkill. If a page has had a typo for 3 releases, do you need to
backport a small change to all those branches?

We should agree on some guidelines around this. We can use existing
conventions to start - if you found a typo in the javadocs and chose
to fix it, would you backport it to all the active branches? It seems
to me that people generally don't do that, and I think we could apply
the same principle here. The key point being we could agree to this
and write it down.

> Make no mistake, for all the numerous benefits of moving to a source-control
> based editing, it will become harder to make small edits/fixes to the docs.
> In under 15 seconds I can fix any trivial typo in Confluence.  We need to
> recognize this with eyes wide open before choosing the trade-offs.  I still
> think it will be a worthwhile trade-off *if* we strive to make editing the
> docs in the new system as easy as possible.  Needing to usually commit to
> two branches is a *huge* blow to that.  As it is, apparently I need to go
> finding some asciidoc IDE that I didn't need yet.  Not for typo fixes of
> course, but any way my browser isn't enough any more.
>

You don't need an IDE. The tools that have been mentioned are only to
preview an Asciidoc page as HTML, as an aid to see your changes as you
make them and not a requirement. Asciidoc is just like Markdown -
mostly the same syntaxes, and the changes are mostly additions to
extend the capabilities of Markdown. But it's a markup language, so
for some edits it's easier to see what it might look like online.

(By the way, the paragraph I just wrote is 100% valid Asciidoc, no IDE
required.)

I definitely hear your point about it being really simple to fix small
things today. There is no perfect solution, everything has one
drawback or another. Today you don't have the problem of having to
backport it, because we have no way of having docs for different
versions. If we want maintainable docs for other versions - the idea
came up again a few months ago when the idea of a Solr 5.6 was
initially raised - we'll have to address the issue of how to maintain
those prior versions.

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[Alexandre Rafalovitch]

On 19 August 2016 at 13:38, Erick Erickson  wrote:
> Does GitHub have any edit-in-place magic? Kind of seems contrary to
> the spirit of Git though


Yes, it does. It even clones the repo and does pull request afterwards
if you don't have access directly.

Regards,
   Alex.

Newsletter and resources for Solr beginners and intermediates:
http://www.solr-start.com/

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[Erick Erickson]

Does GitHub have any edit-in-place magic? Kind of seems contrary to
the spirit of Git though

The other question I have is how to find the file I want to edit. I'm
taking it on faith that there's a way to find a particular asciidoc
file without resorting to a recursive grep, but if not I can cope with
that since every damn major edit I've wanted to do on Confluence has
caused a dangerous rise in my blood pressure.

On Thu, Aug 18, 2016 at 6:48 PM, David Smiley  wrote:
> Everything here sounds great (+1 from me) but...
>
> On Thu, Aug 18, 2016 at 7:30 PM Chris Hostetter 
> wrote:
>>
>> But the other nice thing is that this will make it easy to
>> maintain "branches" of the ref guide in git, and publish those with
>> releases as well -- so you can edit the docs on master, and backport the
>> docs to the branch_6x at the same you backport the feature, and we can
>> publish HTML versions of the guide right along side the javadoc docs for
>> each version of solr.
>
>
> Ugh!  I think it's a PITA that we basically always back-port all commits to
> another branch, and the prospect of having to do this to documentation as
> well will add a large barrier to editing the docs.  I propose an alternative
> way:  Like having everything go into a 6x branch and then have the 7x branch
> be only for things unique to 7x?  From time to time and definitely when 7.0
> arrives, we then merge 6x into 7x.  Some things we will need to remember to
> remove from 7x, and there will be merge conflicts, but I think the
> down-sides there far outweigh the lower barrier to editing the
> documentation.
>
> Make no mistake, for all the numerous benefits of moving to a source-control
> based editing, it will become harder to make small edits/fixes to the docs.
> In under 15 seconds I can fix any trivial typo in Confluence.  We need to
> recognize this with eyes wide open before choosing the trade-offs.  I still
> think it will be a worthwhile trade-off *if* we strive to make editing the
> docs in the new system as easy as possible.  Needing to usually commit to
> two branches is a *huge* blow to that.  As it is, apparently I need to go
> finding some asciidoc IDE that I didn't need yet.  Not for typo fixes of
> course, but any way my browser isn't enough any more.
>
> ~ David
> --
> Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker
> LinkedIn: http://linkedin.com/in/davidwsmiley | Book:
> http://www.solrenterprisesearchserver.com

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[David Smiley]

Everything here sounds great (+1 from me) but...

On Thu, Aug 18, 2016 at 7:30 PM Chris Hostetter 
wrote:

> But the other nice thing is that this will make it easy to
> maintain "branches" of the ref guide in git, and publish those with
> releases as well -- so you can edit the docs on master, and backport the
> docs to the branch_6x at the same you backport the feature, and we can
> publish HTML versions of the guide right along side the javadoc docs for
> each version of solr.
>

Ugh!  I think it's a PITA that we basically always back-port all commits to
another branch, and the prospect of having to do this to documentation as
well will add a large barrier to editing the docs.  I propose an
alternative way:  Like having everything go into a 6x branch and then have
the 7x branch be only for things unique to 7x?  From time to time and
definitely when 7.0 arrives, we then merge 6x into 7x.  Some things we will
need to remember to remove from 7x, and there will be merge conflicts, but
I think the down-sides there far outweigh the lower barrier to editing the
documentation.

Make no mistake, for all the numerous benefits of moving to a
source-control based editing, it will become harder to make small
edits/fixes to the docs.  In under 15 seconds I can fix any trivial typo in
Confluence.  We need to recognize this with eyes wide open before choosing
the trade-offs.  I still think it will be a worthwhile trade-off *if* we
strive to make editing the docs in the new system as easy as possible.
Needing to usually commit to two branches is a *huge* blow to that.  As it
is, apparently I need to go finding some asciidoc IDE that I didn't need
yet.  Not for typo fixes of course, but any way my browser isn't enough any
more.

~ David
-- 
Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker
LinkedIn: http://linkedin.com/in/davidwsmiley | Book:
http://www.solrenterprisesearchserver.com

Re: Proposal to Move Solr Ref Guide off Confluence

[Chris Hostetter]

: Is there anyway to maintain inbound links to confluence pages with the new
: system? I'm just thinking about all the user group questions, stackoverflow
: Qs, and the like that link to cwiki pages.
: 
: Is it possible to setup the right redirects for cwiki pages into the new
: system?

That should be possible, yeah.

Worst case scenerio: confluence has a redirect macro we can manually put 
on every page pointing to the new equivilent URL

Best case scenerio: we talk to infra about letting us upload a mod_rewrite 
mapping file.



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

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[Doug Turnbull]

Is there anyway to maintain inbound links to confluence pages with the new
system? I'm just thinking about all the user group questions, stackoverflow
Qs, and the like that link to cwiki pages.

Is it possible to setup the right redirects for cwiki pages into the new
system?

Doug
On Thu, Aug 18, 2016 at 7:30 PM Chris Hostetter 
wrote:

>
> : First, I'm not about to second-guess this. I wouldn't like to lose the
> : ability to download a full doc to search offline, but it looks like
> : this solution allows that since there is a PDF version after all.
>
> I also like being able to officially "release" the guide, and doing so via
> PDF will still be possible.
>
> But the other nice thing is that this will make it easy to
> maintain "branches" of the ref guide in git, and publish those with
> releases as well -- so you can edit the docs on master, and backport the
> docs to the branch_6x at the same you backport the feature, and we can
> publish HTML versions of the guide right along side the javadoc docs for
> each version of solr.
>
> : As you know, every time I try to edit he CWiki I come whimpering to
> : you or Hoss. Sounds like this solution will reduce the volume of my
> : whimpering which is a good thing. I so loathe Confluence that find
>
> Ideally yes -- a lot of the problems we have with confluence today stem
> from the "WYSI-kind-of-WYG" mentality of it's editor, and the fact that it
> sometimes preserves html styling you can't see until the PDF is published
> (especially when you copy/paste).  Most of that pain should go away
> because the adoc files will be plain text.  (Any markup langauge has it's
> share of "wait, how do i get get formatting XYZ?" but being plain text
> files in git will make it a lot easier to spot mistakes in diffs -- as
> opposed to confluence with it's "heres a historical diff that is also in
> rendered HTML, so good luck noticing that there is an extra span with a
> css class that affects the PDF but isn't mentioned in the web stylesheet"
>
> : I downloaded AsciidocFX and it looks quite usable. There may be better
> : tools out there but that was fast to find and I could work with it. I
> : see a Chrome extension, IntelliJ plugin etc. so it looks like there
> : are a variety of ways to go about all this.
>
> yeah -- just like java IDE/editor choices can be very personal,
> people will also be free to choose any tooling they want for editing
> asciidoc files -- which is another nice win over the web based confluence
> editor.  The trick will be having good automation in place to build the
> HTML & PDF output formats from the source documents, and give helpful
> feedback/errors about any weirdness that we can detect in scripts.  I plan
> on working to help cassandra with the "ongoing automation" when i get back
> from vacation in a few weeks.
>
> (at the moment, I'm spending my last few days before vacation tyring to
> better automate the confluence->(clean)asciidoc conversion so
> cassandra can iterate faster on demos of the full guide)
>
> : > If reaction is positive, my next step will be to expand the demo
> : > online with a full copy of the Ref Guide instead of the current small
> : > set.
>
>
>
> -Hoss
> http://www.lucidworks.com/
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: dev-h...@lucene.apache.org
>
>

Re: Proposal to Move Solr Ref Guide off Confluence

[Chris Hostetter]

: First, I'm not about to second-guess this. I wouldn't like to lose the
: ability to download a full doc to search offline, but it looks like
: this solution allows that since there is a PDF version after all.

I also like being able to officially "release" the guide, and doing so via 
PDF will still be possible.

But the other nice thing is that this will make it easy to 
maintain "branches" of the ref guide in git, and publish those with 
releases as well -- so you can edit the docs on master, and backport the 
docs to the branch_6x at the same you backport the feature, and we can 
publish HTML versions of the guide right along side the javadoc docs for 
each version of solr.

: As you know, every time I try to edit he CWiki I come whimpering to
: you or Hoss. Sounds like this solution will reduce the volume of my
: whimpering which is a good thing. I so loathe Confluence that find

Ideally yes -- a lot of the problems we have with confluence today stem 
from the "WYSI-kind-of-WYG" mentality of it's editor, and the fact that it 
sometimes preserves html styling you can't see until the PDF is published 
(especially when you copy/paste).  Most of that pain should go away 
because the adoc files will be plain text.  (Any markup langauge has it's 
share of "wait, how do i get get formatting XYZ?" but being plain text 
files in git will make it a lot easier to spot mistakes in diffs -- as 
opposed to confluence with it's "heres a historical diff that is also in 
rendered HTML, so good luck noticing that there is an extra span with a 
css class that affects the PDF but isn't mentioned in the web stylesheet"

: I downloaded AsciidocFX and it looks quite usable. There may be better
: tools out there but that was fast to find and I could work with it. I
: see a Chrome extension, IntelliJ plugin etc. so it looks like there
: are a variety of ways to go about all this.

yeah -- just like java IDE/editor choices can be very personal, 
people will also be free to choose any tooling they want for editing 
asciidoc files -- which is another nice win over the web based confluence 
editor.  The trick will be having good automation in place to build the 
HTML & PDF output formats from the source documents, and give helpful 
feedback/errors about any weirdness that we can detect in scripts.  I plan 
on working to help cassandra with the "ongoing automation" when i get back 
from vacation in a few weeks.  

(at the moment, I'm spending my last few days before vacation tyring to 
better automate the confluence->(clean)asciidoc conversion so 
cassandra can iterate faster on demos of the full guide)

: > If reaction is positive, my next step will be to expand the demo
: > online with a full copy of the Ref Guide instead of the current small
: > set.



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

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[Erick Erickson]

First, I'm not about to second-guess this. I wouldn't like to lose the
ability to download a full doc to search offline, but it looks like
this solution allows that since there is a PDF version after all.


As you know, every time I try to edit he CWiki I come whimpering to
you or Hoss. Sounds like this solution will reduce the volume of my
whimpering which is a good thing. I so loathe Confluence that find
myself reluctant to do much with it beyond the very simplest editing,
starting a new section is daunting. Removing that barrier to entry is
a huge plus IMO.

I downloaded AsciidocFX and it looks quite usable. There may be better
tools out there but that was fast to find and I could work with it. I
see a Chrome extension, IntelliJ plugin etc. so it looks like there
are a variety of ways to go about all this.

So +1 from my perspective.
Erick

On Thu, Aug 18, 2016 at 2:54 PM, Jan Høydahl  wrote:
> I was thinking about Asciidoc as well the other day, I love it!
>
> +1
>
> --
> Jan Høydahl, search solution architect
> Cominvent AS - www.cominvent.com
>
> 18. aug. 2016 kl. 21.45 skrev Cassandra Targett :
>
> When the Solr Ref Guide was donated back in 2013, we decided to host
> it in Confluence (cwiki) because the source had originated from a
> Confluence system, and it made the handoff easier. Today, though, it
> has become really painful to maintain there.[1]
>
> I'll suggest that it's time to move from Confluence to something else.
>
> As a replacement, I propose to migrate all of the existing content to
> text files in Asciidoc format. This is a lightweight markup language
> similar to Markdown, but intended for use by writers.
>
> We can then use a static site generator (I've chosen Jekyll) to
> produce templated HTML pages, and Asciidoctor tools to make PDFs (and
> ePub if we want).
>
> At this point, we'd be able to treat the docs the same way we do code
> - source controlled and open for patches by anyone. We can integrate
> the doc publication process with the release process (as much or as
> little as we choose).
>
> With the Apache Comment System, we would retain the ability for users
> to comment on pages. Since we'd control the hosting, we can choose
> which versions we retain online for users. The source for each version
> would be maintained in the appropriate branch, allowing us to go back
> at any time and edit older versions when necessary (or build a new
> version from an older branch).
>
> I've worked up a proof of concept for these ideas, and have most of
> the building blocks for this solution in place in a GitHub repo at
> https://github.com/ctargett/refguide-asciidoc-poc.
>
> I've used that to put up a demo of the various ideas I worked through,
> to show what it might look like online and in PDF, at
> http://home.apache.org/~ctargett/RefGuidePOC/.
>
> I'm trying to keep this introductory mail brief but if you want more
> info, I've fleshed out a lot of details of the approach (and how I
> made a few key decisions) in the README and other pages in the GitHub
> repo linked above.
>
> There are still a number of issues to work out - where the pages will
> actually live, where they'll be hosted, how we'll implement search
> (heh), finishing the styling, finalizing the build scripts, etc. But I
> hope the project shows enough promise that we'll agree to move forward
> with this approach.
>
> If reaction is positive, my next step will be to expand the demo
> online with a full copy of the Ref Guide instead of the current small
> set.
>
> I look forward to hearing your thoughts or questions about this proposal.
>
> Cassandra
>
>
> [1] For those who have avoided the pleasure of working with
> Confluence, there are many reasons to move off Confluence, but here
> are a few:
>
> * Confluence as a product is no longer designed for our use case and
> our type of content. While technical documentation was once a core
> competency, the product is now much more focused on team
> collaboration. This shift has left us out a bit.
> * The writing/editing experience is painful and a barrier for all
> users, who need to learn a lot of Confluence-specific syntax just to
> help out with some content. Non-committers can't really help much
> except to point out problems and hope someone else fixes them.
> Committer involvement is low, and perhaps could be improved with a
> solution that's easier to use.
> * We really can't maintain online documentation for different
> versions. Users on versions other than the one that hasn't been
> released yet are only given a PDF to work with.
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: dev-h...@lucene.apache.org
>
>

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[Alexandre Rafalovitch]

+1 with Asciidoc and moving off Confluence and into anything that
allows to generate stable-version HTML export. Offline builds that can
also be used for tooling (e.g. for search index generation) is also
great. I had a quick look at indexing Confluence export and it is a
confusing mess (though I am sure possible).

Regards,
  Alex.

Newsletter and resources for Solr beginners and intermediates:
http://www.solr-start.com/


On 19 August 2016 at 07:54, Jan Høydahl  wrote:
> I was thinking about Asciidoc as well the other day, I love it!
>
> +1
>
> --
> Jan Høydahl, search solution architect
> Cominvent AS - www.cominvent.com
>
> 18. aug. 2016 kl. 21.45 skrev Cassandra Targett :
>
> When the Solr Ref Guide was donated back in 2013, we decided to host
> it in Confluence (cwiki) because the source had originated from a
> Confluence system, and it made the handoff easier. Today, though, it
> has become really painful to maintain there.[1]
>
> I'll suggest that it's time to move from Confluence to something else.
>
> As a replacement, I propose to migrate all of the existing content to
> text files in Asciidoc format. This is a lightweight markup language
> similar to Markdown, but intended for use by writers.
>
> We can then use a static site generator (I've chosen Jekyll) to
> produce templated HTML pages, and Asciidoctor tools to make PDFs (and
> ePub if we want).
>
> At this point, we'd be able to treat the docs the same way we do code
> - source controlled and open for patches by anyone. We can integrate
> the doc publication process with the release process (as much or as
> little as we choose).
>
> With the Apache Comment System, we would retain the ability for users
> to comment on pages. Since we'd control the hosting, we can choose
> which versions we retain online for users. The source for each version
> would be maintained in the appropriate branch, allowing us to go back
> at any time and edit older versions when necessary (or build a new
> version from an older branch).
>
> I've worked up a proof of concept for these ideas, and have most of
> the building blocks for this solution in place in a GitHub repo at
> https://github.com/ctargett/refguide-asciidoc-poc.
>
> I've used that to put up a demo of the various ideas I worked through,
> to show what it might look like online and in PDF, at
> http://home.apache.org/~ctargett/RefGuidePOC/.
>
> I'm trying to keep this introductory mail brief but if you want more
> info, I've fleshed out a lot of details of the approach (and how I
> made a few key decisions) in the README and other pages in the GitHub
> repo linked above.
>
> There are still a number of issues to work out - where the pages will
> actually live, where they'll be hosted, how we'll implement search
> (heh), finishing the styling, finalizing the build scripts, etc. But I
> hope the project shows enough promise that we'll agree to move forward
> with this approach.
>
> If reaction is positive, my next step will be to expand the demo
> online with a full copy of the Ref Guide instead of the current small
> set.
>
> I look forward to hearing your thoughts or questions about this proposal.
>
> Cassandra
>
>
> [1] For those who have avoided the pleasure of working with
> Confluence, there are many reasons to move off Confluence, but here
> are a few:
>
> * Confluence as a product is no longer designed for our use case and
> our type of content. While technical documentation was once a core
> competency, the product is now much more focused on team
> collaboration. This shift has left us out a bit.
> * The writing/editing experience is painful and a barrier for all
> users, who need to learn a lot of Confluence-specific syntax just to
> help out with some content. Non-committers can't really help much
> except to point out problems and hope someone else fixes them.
> Committer involvement is low, and perhaps could be improved with a
> solution that's easier to use.
> * We really can't maintain online documentation for different
> versions. Users on versions other than the one that hasn't been
> released yet are only given a PDF to work with.
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: dev-h...@lucene.apache.org
>
>

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: Proposal to Move Solr Ref Guide off Confluence

[Jan Høydahl]

I was thinking about Asciidoc as well the other day, I love it!

+1

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com

> 18. aug. 2016 kl. 21.45 skrev Cassandra Targett :
> 
> When the Solr Ref Guide was donated back in 2013, we decided to host
> it in Confluence (cwiki) because the source had originated from a
> Confluence system, and it made the handoff easier. Today, though, it
> has become really painful to maintain there.[1]
> 
> I'll suggest that it's time to move from Confluence to something else.
> 
> As a replacement, I propose to migrate all of the existing content to
> text files in Asciidoc format. This is a lightweight markup language
> similar to Markdown, but intended for use by writers.
> 
> We can then use a static site generator (I've chosen Jekyll) to
> produce templated HTML pages, and Asciidoctor tools to make PDFs (and
> ePub if we want).
> 
> At this point, we'd be able to treat the docs the same way we do code
> - source controlled and open for patches by anyone. We can integrate
> the doc publication process with the release process (as much or as
> little as we choose).
> 
> With the Apache Comment System, we would retain the ability for users
> to comment on pages. Since we'd control the hosting, we can choose
> which versions we retain online for users. The source for each version
> would be maintained in the appropriate branch, allowing us to go back
> at any time and edit older versions when necessary (or build a new
> version from an older branch).
> 
> I've worked up a proof of concept for these ideas, and have most of
> the building blocks for this solution in place in a GitHub repo at
> https://github.com/ctargett/refguide-asciidoc-poc.
> 
> I've used that to put up a demo of the various ideas I worked through,
> to show what it might look like online and in PDF, at
> http://home.apache.org/~ctargett/RefGuidePOC/.
> 
> I'm trying to keep this introductory mail brief but if you want more
> info, I've fleshed out a lot of details of the approach (and how I
> made a few key decisions) in the README and other pages in the GitHub
> repo linked above.
> 
> There are still a number of issues to work out - where the pages will
> actually live, where they'll be hosted, how we'll implement search
> (heh), finishing the styling, finalizing the build scripts, etc. But I
> hope the project shows enough promise that we'll agree to move forward
> with this approach.
> 
> If reaction is positive, my next step will be to expand the demo
> online with a full copy of the Ref Guide instead of the current small
> set.
> 
> I look forward to hearing your thoughts or questions about this proposal.
> 
> Cassandra
> 
> 
> [1] For those who have avoided the pleasure of working with
> Confluence, there are many reasons to move off Confluence, but here
> are a few:
> 
> * Confluence as a product is no longer designed for our use case and
> our type of content. While technical documentation was once a core
> competency, the product is now much more focused on team
> collaboration. This shift has left us out a bit.
> * The writing/editing experience is painful and a barrier for all
> users, who need to learn a lot of Confluence-specific syntax just to
> help out with some content. Non-committers can't really help much
> except to point out problems and hope someone else fixes them.
> Committer involvement is low, and perhaps could be improved with a
> solution that's easier to use.
> * We really can't maintain online documentation for different
> versions. Users on versions other than the one that hasn't been
> released yet are only given a PDF to work with.
> 
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: dev-h...@lucene.apache.org
> 

Proposal to Move Solr Ref Guide off Confluence

[Cassandra Targett]

When the Solr Ref Guide was donated back in 2013, we decided to host
it in Confluence (cwiki) because the source had originated from a
Confluence system, and it made the handoff easier. Today, though, it
has become really painful to maintain there.[1]

I'll suggest that it's time to move from Confluence to something else.

As a replacement, I propose to migrate all of the existing content to
text files in Asciidoc format. This is a lightweight markup language
similar to Markdown, but intended for use by writers.

We can then use a static site generator (I've chosen Jekyll) to
produce templated HTML pages, and Asciidoctor tools to make PDFs (and
ePub if we want).

At this point, we'd be able to treat the docs the same way we do code
- source controlled and open for patches by anyone. We can integrate
the doc publication process with the release process (as much or as
little as we choose).

With the Apache Comment System, we would retain the ability for users
to comment on pages. Since we'd control the hosting, we can choose
which versions we retain online for users. The source for each version
would be maintained in the appropriate branch, allowing us to go back
at any time and edit older versions when necessary (or build a new
version from an older branch).

I've worked up a proof of concept for these ideas, and have most of
the building blocks for this solution in place in a GitHub repo at
https://github.com/ctargett/refguide-asciidoc-poc.

I've used that to put up a demo of the various ideas I worked through,
to show what it might look like online and in PDF, at
http://home.apache.org/~ctargett/RefGuidePOC/.

I'm trying to keep this introductory mail brief but if you want more
info, I've fleshed out a lot of details of the approach (and how I
made a few key decisions) in the README and other pages in the GitHub
repo linked above.

There are still a number of issues to work out - where the pages will
actually live, where they'll be hosted, how we'll implement search
(heh), finishing the styling, finalizing the build scripts, etc. But I
hope the project shows enough promise that we'll agree to move forward
with this approach.

If reaction is positive, my next step will be to expand the demo
online with a full copy of the Ref Guide instead of the current small
set.

I look forward to hearing your thoughts or questions about this proposal.

Cassandra


[1] For those who have avoided the pleasure of working with
Confluence, there are many reasons to move off Confluence, but here
are a few:

* Confluence as a product is no longer designed for our use case and
our type of content. While technical documentation was once a core
competency, the product is now much more focused on team
collaboration. This shift has left us out a bit.
* The writing/editing experience is painful and a barrier for all
users, who need to learn a lot of Confluence-specific syntax just to
help out with some content. Non-committers can't really help much
except to point out problems and hope someone else fixes them.
Committer involvement is low, and perhaps could be improved with a
solution that's easier to use.
* We really can't maintain online documentation for different
versions. Users on versions other than the one that hasn't been
released yet are only given a PDF to work with.

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org