[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[
https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16612671#comment-16612671
]
Cassandra Targett commented on SOLR-10290:
--
That was the tiniest of typos - a {{#}} instead of a {{$}}! Thanks! Here are
the commits that fix it:
master: ad7f15d808232572c8755967559f440c742a2352
branch_7x: 1a8a6eafe0220a40935d2aa9f5d4cf0b6d2eaa4b
branch_7_5: b20f0c703dbba466a3e92b57673310ee88c5ef20
> New Publication Model for Solr Reference Guide
> --
>
> Key: SOLR-10290
> URL: https://issues.apache.org/jira/browse/SOLR-10290
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
>Reporter: Cassandra Targett
>Priority: Major
> Attachments: sitemap.patch, sitemap.patch
>
>
> The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence
> installation. There are numerous reasons to be dissatisfied with the current
> setup, a few of which are:
> * Confluence as a product is no longer designed for our use case and our type
> of content.
> * 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 improve documentation except to point out
> problems and hope someone else fixes them.
> * 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.
> I made a proposal in Aug 2016 ([email
> link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E])
> to move the Ref Guide from Confluence to a new system that relies on
> asciidoc-formatted text files integrated with the Solr source code.
> This is an umbrella issue for the sub-tasks and related decisions to make
> that proposal a reality. A lot of work has already been done as part of a
> proof-of-concept, but there are many things left to do. Some of the items to
> be completed include:
> * Creation of a branch and moving the early POC work I've done to the project
> * Conversion the content and clean up of unavoidable post-conversion issues
> * Decisions about location of source files, branching strategy and hosting
> for online versions
> * Meta-documentation for publication process, beginner tips, etc. (whatever
> else people need or want)
> * Integration of build processes with the broader project
> For reference, a demo of what the new ref guide might look like is currently
> online at http://people.apache.org/~ctargett/RefGuidePOC/.
> Creation of sub-tasks to follow shortly.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16612655#comment-16612655 ] Cassandra Targett commented on SOLR-10290: -- Thanks Christine, that must be a recent breakage, I will investigate and fix it. > New Publication Model for Solr Reference Guide > -- > > Key: SOLR-10290 > URL: https://issues.apache.org/jira/browse/SOLR-10290 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Components: documentation >Reporter: Cassandra Targett >Priority: Major > Attachments: sitemap.patch, sitemap.patch > > > The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence > installation. There are numerous reasons to be dissatisfied with the current > setup, a few of which are: > * Confluence as a product is no longer designed for our use case and our type > of content. > * 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 improve documentation except to point out > problems and hope someone else fixes them. > * 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. > I made a proposal in Aug 2016 ([email > link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E]) > to move the Ref Guide from Confluence to a new system that relies on > asciidoc-formatted text files integrated with the Solr source code. > This is an umbrella issue for the sub-tasks and related decisions to make > that proposal a reality. A lot of work has already been done as part of a > proof-of-concept, but there are many things left to do. Some of the items to > be completed include: > * Creation of a branch and moving the early POC work I've done to the project > * Conversion the content and clean up of unavoidable post-conversion issues > * Decisions about location of source files, branching strategy and hosting > for online versions > * Meta-documentation for publication process, beginner tips, etc. (whatever > else people need or want) > * Integration of build processes with the broader project > For reference, a demo of what the new ref guide might look like is currently > online at http://people.apache.org/~ctargett/RefGuidePOC/. > Creation of sub-tasks to follow shortly. -- This message was sent by Atlassian JIRA (v7.6.3#76005) - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[
https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16612614#comment-16612614
]
Christine Poerschke commented on SOLR-10290:
Hello. Not sure if this is the best place to ask or if it is a known issue ...
I stumbled across odd-looking javadocs links in the .pdf version of the Solr
Reference Guide e.g. in 7.4 search for (say) {{SynonymMap.Builder.html}} or
{{SynonymMap.Builder}} and it shows (literally)
{code}
#{pdf-lucene-javadocs}/analyzers-
common/org/apache/lucene/analysis/synonym/SynonymMap.Builder.html[SynonymMap.Builder]
{code}
whereas the online equivalent is fine e.g.
http://lucene.apache.org/solr/guide/7_4/filter-descriptions.html#synonym-graph-filter
in this case. The issue seems to be specific to {{\{lucene-javadocs\}}} i.e.
the {{\{solr-javadocs\}}} links i checked were fine.
> New Publication Model for Solr Reference Guide
> --
>
> Key: SOLR-10290
> URL: https://issues.apache.org/jira/browse/SOLR-10290
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
>Reporter: Cassandra Targett
>Priority: Major
> Attachments: sitemap.patch, sitemap.patch
>
>
> The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence
> installation. There are numerous reasons to be dissatisfied with the current
> setup, a few of which are:
> * Confluence as a product is no longer designed for our use case and our type
> of content.
> * 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 improve documentation except to point out
> problems and hope someone else fixes them.
> * 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.
> I made a proposal in Aug 2016 ([email
> link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E])
> to move the Ref Guide from Confluence to a new system that relies on
> asciidoc-formatted text files integrated with the Solr source code.
> This is an umbrella issue for the sub-tasks and related decisions to make
> that proposal a reality. A lot of work has already been done as part of a
> proof-of-concept, but there are many things left to do. Some of the items to
> be completed include:
> * Creation of a branch and moving the early POC work I've done to the project
> * Conversion the content and clean up of unavoidable post-conversion issues
> * Decisions about location of source files, branching strategy and hosting
> for online versions
> * Meta-documentation for publication process, beginner tips, etc. (whatever
> else people need or want)
> * Integration of build processes with the broader project
> For reference, a demo of what the new ref guide might look like is currently
> online at http://people.apache.org/~ctargett/RefGuidePOC/.
> Creation of sub-tasks to follow shortly.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16031970#comment-16031970 ] ASF subversion and git services commented on SOLR-10290: Commit fc8be1c1620363793b7e280645ca589e27041c9a in lucene-solr's branch refs/heads/branch_6x from [~ctargett] [ https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=fc8be1c ] SOLR-10290: Replace the bright green in the bottom nav links with a lighter tone of the header > New Publication Model for Solr Reference Guide > -- > > Key: SOLR-10290 > URL: https://issues.apache.org/jira/browse/SOLR-10290 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Components: documentation >Reporter: Cassandra Targett > Attachments: sitemap.patch, sitemap.patch > > > The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence > installation. There are numerous reasons to be dissatisfied with the current > setup, a few of which are: > * Confluence as a product is no longer designed for our use case and our type > of content. > * 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 improve documentation except to point out > problems and hope someone else fixes them. > * 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. > I made a proposal in Aug 2016 ([email > link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E]) > to move the Ref Guide from Confluence to a new system that relies on > asciidoc-formatted text files integrated with the Solr source code. > This is an umbrella issue for the sub-tasks and related decisions to make > that proposal a reality. A lot of work has already been done as part of a > proof-of-concept, but there are many things left to do. Some of the items to > be completed include: > * Creation of a branch and moving the early POC work I've done to the project > * Conversion the content and clean up of unavoidable post-conversion issues > * Decisions about location of source files, branching strategy and hosting > for online versions > * Meta-documentation for publication process, beginner tips, etc. (whatever > else people need or want) > * Integration of build processes with the broader project > For reference, a demo of what the new ref guide might look like is currently > online at http://people.apache.org/~ctargett/RefGuidePOC/. > Creation of sub-tasks to follow shortly. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16031972#comment-16031972 ] ASF subversion and git services commented on SOLR-10290: Commit 41268b175c0ef41cba36442bbc76d3ea787d93cd in lucene-solr's branch refs/heads/branch_6_6 from [~ctargett] [ https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=41268b1 ] SOLR-10290: Replace the bright green in the bottom nav links with a lighter tone of the header > New Publication Model for Solr Reference Guide > -- > > Key: SOLR-10290 > URL: https://issues.apache.org/jira/browse/SOLR-10290 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Components: documentation >Reporter: Cassandra Targett > Attachments: sitemap.patch, sitemap.patch > > > The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence > installation. There are numerous reasons to be dissatisfied with the current > setup, a few of which are: > * Confluence as a product is no longer designed for our use case and our type > of content. > * 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 improve documentation except to point out > problems and hope someone else fixes them. > * 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. > I made a proposal in Aug 2016 ([email > link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E]) > to move the Ref Guide from Confluence to a new system that relies on > asciidoc-formatted text files integrated with the Solr source code. > This is an umbrella issue for the sub-tasks and related decisions to make > that proposal a reality. A lot of work has already been done as part of a > proof-of-concept, but there are many things left to do. Some of the items to > be completed include: > * Creation of a branch and moving the early POC work I've done to the project > * Conversion the content and clean up of unavoidable post-conversion issues > * Decisions about location of source files, branching strategy and hosting > for online versions > * Meta-documentation for publication process, beginner tips, etc. (whatever > else people need or want) > * Integration of build processes with the broader project > For reference, a demo of what the new ref guide might look like is currently > online at http://people.apache.org/~ctargett/RefGuidePOC/. > Creation of sub-tasks to follow shortly. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16031968#comment-16031968 ] ASF subversion and git services commented on SOLR-10290: Commit f34155fb2014393da50a836a1b78416c406b0dfd in lucene-solr's branch refs/heads/master from [~ctargett] [ https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=f34155f ] SOLR-10290: Replace the bright green in the bottom nav links with a lighter tone of the header > New Publication Model for Solr Reference Guide > -- > > Key: SOLR-10290 > URL: https://issues.apache.org/jira/browse/SOLR-10290 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Components: documentation >Reporter: Cassandra Targett > Attachments: sitemap.patch, sitemap.patch > > > The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence > installation. There are numerous reasons to be dissatisfied with the current > setup, a few of which are: > * Confluence as a product is no longer designed for our use case and our type > of content. > * 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 improve documentation except to point out > problems and hope someone else fixes them. > * 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. > I made a proposal in Aug 2016 ([email > link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E]) > to move the Ref Guide from Confluence to a new system that relies on > asciidoc-formatted text files integrated with the Solr source code. > This is an umbrella issue for the sub-tasks and related decisions to make > that proposal a reality. A lot of work has already been done as part of a > proof-of-concept, but there are many things left to do. Some of the items to > be completed include: > * Creation of a branch and moving the early POC work I've done to the project > * Conversion the content and clean up of unavoidable post-conversion issues > * Decisions about location of source files, branching strategy and hosting > for online versions > * Meta-documentation for publication process, beginner tips, etc. (whatever > else people need or want) > * Integration of build processes with the broader project > For reference, a demo of what the new ref guide might look like is currently > online at http://people.apache.org/~ctargett/RefGuidePOC/. > Creation of sub-tasks to follow shortly. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[
https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16019868#comment-16019868
]
Cassandra Targett commented on SOLR-10290:
--
For removing feed.xml, I think you will also need to remove it from the
head.html at line 35.
For the {{_config.yml.template}} changes, there is no
{{solr-docs-version-path}} attribute, the one we have is {{solr-docs-version}}.
But that would make the URL {{https://lucene.apache.org/solr/guide/6.6}} which
is inconsistent with paths we use elsewhere, as in Javadocs. In the
{{sitemap.xml}} liquid template, I believe you could try a [replace
filter|https://help.shopify.com/themes/liquid/filters/string-filters#replace]
on the {{site.url}} to transform it to a underscore? May need to play around
with that.
And, my thought is that we should stick to
{{https://lucene.apache.org/solr/guide/6_6}} to keep things simple - Hoss added
guide versions in SOLR-10675, and those will be on each page and in the footer
of the PDF.
> New Publication Model for Solr Reference Guide
> --
>
> Key: SOLR-10290
> URL: https://issues.apache.org/jira/browse/SOLR-10290
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
>Reporter: Cassandra Targett
> Attachments: sitemap.patch
>
>
> The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence
> installation. There are numerous reasons to be dissatisfied with the current
> setup, a few of which are:
> * Confluence as a product is no longer designed for our use case and our type
> of content.
> * 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 improve documentation except to point out
> problems and hope someone else fixes them.
> * 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.
> I made a proposal in Aug 2016 ([email
> link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E])
> to move the Ref Guide from Confluence to a new system that relies on
> asciidoc-formatted text files integrated with the Solr source code.
> This is an umbrella issue for the sub-tasks and related decisions to make
> that proposal a reality. A lot of work has already been done as part of a
> proof-of-concept, but there are many things left to do. Some of the items to
> be completed include:
> * Creation of a branch and moving the early POC work I've done to the project
> * Conversion the content and clean up of unavoidable post-conversion issues
> * Decisions about location of source files, branching strategy and hosting
> for online versions
> * Meta-documentation for publication process, beginner tips, etc. (whatever
> else people need or want)
> * Integration of build processes with the broader project
> For reference, a demo of what the new ref guide might look like is currently
> online at http://people.apache.org/~ctargett/RefGuidePOC/.
> Creation of sub-tasks to follow shortly.
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[
https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16019594#comment-16019594
]
Cassandra Targett commented on SOLR-10290:
--
I toyed with the idea of disabling the {{feed.xml}} page (it came from the
theme I used to build the HTML pages), but decided it somewhat depended on what
the publication process was, which the last time I looked at this question (in
March) was very much under discussion.
Personally, I think it makes little sense. On every build, every page is "new"
since we don't build HTML pages only for files that have changed since last
time - so a list of 10 pages doesn't really get anyone anywhere. And it's the
same for every build, so my opinion is that it provides no value in it's
current form. It's not on any of my various lists to change it - someone else
would need to care about it to fix it.
Obviously, "fixing" it (and {{sitemap.xml}}) just means fixing the URL in
{{_config.yml.template}}, which needs to be parameterized so it's correct for
every version that's built. Not sure it needs a whole issue for itself. Since
you brought it up here, you could just use this one.
> New Publication Model for Solr Reference Guide
> --
>
> Key: SOLR-10290
> URL: https://issues.apache.org/jira/browse/SOLR-10290
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
>Reporter: Cassandra Targett
>
> The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence
> installation. There are numerous reasons to be dissatisfied with the current
> setup, a few of which are:
> * Confluence as a product is no longer designed for our use case and our type
> of content.
> * 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 improve documentation except to point out
> problems and hope someone else fixes them.
> * 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.
> I made a proposal in Aug 2016 ([email
> link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E])
> to move the Ref Guide from Confluence to a new system that relies on
> asciidoc-formatted text files integrated with the Solr source code.
> This is an umbrella issue for the sub-tasks and related decisions to make
> that proposal a reality. A lot of work has already been done as part of a
> proof-of-concept, but there are many things left to do. Some of the items to
> be completed include:
> * Creation of a branch and moving the early POC work I've done to the project
> * Conversion the content and clean up of unavoidable post-conversion issues
> * Decisions about location of source files, branching strategy and hosting
> for online versions
> * Meta-documentation for publication process, beginner tips, etc. (whatever
> else people need or want)
> * Integration of build processes with the broader project
> For reference, a demo of what the new ref guide might look like is currently
> online at http://people.apache.org/~ctargett/RefGuidePOC/.
> Creation of sub-tasks to follow shortly.
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[
https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16018952#comment-16018952
]
Jan Høydahl commented on SOLR-10290:
Should we create another issue for completing {{sitemap.xml}} and {{feed.xml}}.
One issue is that {{_config.yml.template}} currently uses a hardcoded URL:
{noformat}
# needed for sitemap.xml and feed.xml files
url: https://home.apache.org/~ctargett/RefGuidePOC/jekyll-full
{noformat}
Also, what is feed.xml supposed to provide here? Currently it serves top 10
pages based on title alphabetically, and description tag is full page content...
> New Publication Model for Solr Reference Guide
> --
>
> Key: SOLR-10290
> URL: https://issues.apache.org/jira/browse/SOLR-10290
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
>Reporter: Cassandra Targett
>
> The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence
> installation. There are numerous reasons to be dissatisfied with the current
> setup, a few of which are:
> * Confluence as a product is no longer designed for our use case and our type
> of content.
> * 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 improve documentation except to point out
> problems and hope someone else fixes them.
> * 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.
> I made a proposal in Aug 2016 ([email
> link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E])
> to move the Ref Guide from Confluence to a new system that relies on
> asciidoc-formatted text files integrated with the Solr source code.
> This is an umbrella issue for the sub-tasks and related decisions to make
> that proposal a reality. A lot of work has already been done as part of a
> proof-of-concept, but there are many things left to do. Some of the items to
> be completed include:
> * Creation of a branch and moving the early POC work I've done to the project
> * Conversion the content and clean up of unavoidable post-conversion issues
> * Decisions about location of source files, branching strategy and hosting
> for online versions
> * Meta-documentation for publication process, beginner tips, etc. (whatever
> else people need or want)
> * Integration of build processes with the broader project
> For reference, a demo of what the new ref guide might look like is currently
> online at http://people.apache.org/~ctargett/RefGuidePOC/.
> Creation of sub-tasks to follow shortly.
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16015443#comment-16015443 ] Jan Høydahl commented on SOLR-10290: Yea, those lines are long I just discovered that GitHub renders our adoc sources out of the box (not perfect but ok), that's cool: https://github.com/apache/lucene-solr/blob/master/solr/solr-ref-guide/src/index.adoc > New Publication Model for Solr Reference Guide > -- > > Key: SOLR-10290 > URL: https://issues.apache.org/jira/browse/SOLR-10290 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Components: documentation >Reporter: Cassandra Targett > > The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence > installation. There are numerous reasons to be dissatisfied with the current > setup, a few of which are: > * Confluence as a product is no longer designed for our use case and our type > of content. > * 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 improve documentation except to point out > problems and hope someone else fixes them. > * 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. > I made a proposal in Aug 2016 ([email > link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E]) > to move the Ref Guide from Confluence to a new system that relies on > asciidoc-formatted text files integrated with the Solr source code. > This is an umbrella issue for the sub-tasks and related decisions to make > that proposal a reality. A lot of work has already been done as part of a > proof-of-concept, but there are many things left to do. Some of the items to > be completed include: > * Creation of a branch and moving the early POC work I've done to the project > * Conversion the content and clean up of unavoidable post-conversion issues > * Decisions about location of source files, branching strategy and hosting > for online versions > * Meta-documentation for publication process, beginner tips, etc. (whatever > else people need or want) > * Integration of build processes with the broader project > For reference, a demo of what the new ref guide might look like is currently > online at http://people.apache.org/~ctargett/RefGuidePOC/. > Creation of sub-tasks to follow shortly. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16014709#comment-16014709 ] David Smiley commented on SOLR-10290: - Can we auto-linewrap the asciidoc content we've imported somehow? The lines are super-long in my IDE (IntelliJ). I can toggle the active editor's "soft wrap" at least (View menu, then Active Editor menu). > New Publication Model for Solr Reference Guide > -- > > Key: SOLR-10290 > URL: https://issues.apache.org/jira/browse/SOLR-10290 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Components: documentation >Reporter: Cassandra Targett > > The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence > installation. There are numerous reasons to be dissatisfied with the current > setup, a few of which are: > * Confluence as a product is no longer designed for our use case and our type > of content. > * 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 improve documentation except to point out > problems and hope someone else fixes them. > * 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. > I made a proposal in Aug 2016 ([email > link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E]) > to move the Ref Guide from Confluence to a new system that relies on > asciidoc-formatted text files integrated with the Solr source code. > This is an umbrella issue for the sub-tasks and related decisions to make > that proposal a reality. A lot of work has already been done as part of a > proof-of-concept, but there are many things left to do. Some of the items to > be completed include: > * Creation of a branch and moving the early POC work I've done to the project > * Conversion the content and clean up of unavoidable post-conversion issues > * Decisions about location of source files, branching strategy and hosting > for online versions > * Meta-documentation for publication process, beginner tips, etc. (whatever > else people need or want) > * Integration of build processes with the broader project > For reference, a demo of what the new ref guide might look like is currently > online at http://people.apache.org/~ctargett/RefGuidePOC/. > Creation of sub-tasks to follow shortly. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16008237#comment-16008237 ] Cassandra Targett commented on SOLR-10290: -- Cherrypicked to branch_6x: https://git1-us-west.apache.org/repos/asf?p=lucene-solr.git;a=commit;h=ccbc93b80929e942d20cd4782e3a3f4c77d73932 Cherrypicked to branch_6_6: https://git1-us-west.apache.org/repos/asf?p=lucene-solr.git;a=commit;h=c8c2aab8dbb1174bf9fd38fdb9dea53e16307f3a > New Publication Model for Solr Reference Guide > -- > > Key: SOLR-10290 > URL: https://issues.apache.org/jira/browse/SOLR-10290 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Components: documentation >Reporter: Cassandra Targett > > The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence > installation. There are numerous reasons to be dissatisfied with the current > setup, a few of which are: > * Confluence as a product is no longer designed for our use case and our type > of content. > * 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 improve documentation except to point out > problems and hope someone else fixes them. > * 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. > I made a proposal in Aug 2016 ([email > link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E]) > to move the Ref Guide from Confluence to a new system that relies on > asciidoc-formatted text files integrated with the Solr source code. > This is an umbrella issue for the sub-tasks and related decisions to make > that proposal a reality. A lot of work has already been done as part of a > proof-of-concept, but there are many things left to do. Some of the items to > be completed include: > * Creation of a branch and moving the early POC work I've done to the project > * Conversion the content and clean up of unavoidable post-conversion issues > * Decisions about location of source files, branching strategy and hosting > for online versions > * Meta-documentation for publication process, beginner tips, etc. (whatever > else people need or want) > * Integration of build processes with the broader project > For reference, a demo of what the new ref guide might look like is currently > online at http://people.apache.org/~ctargett/RefGuidePOC/. > Creation of sub-tasks to follow shortly. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16005503#comment-16005503 ] Hoss Man commented on SOLR-10290: - I just squash merged jira/solr-10290 into master https://git1-us-west.apache.org/repos/asf?p=lucene-solr.git;a=commit;h=95968c69 > New Publication Model for Solr Reference Guide > -- > > Key: SOLR-10290 > URL: https://issues.apache.org/jira/browse/SOLR-10290 > Project: Solr > Issue Type: Improvement > Security Level: Public(Default Security Level. Issues are Public) > Components: documentation >Reporter: Cassandra Targett > > The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence > installation. There are numerous reasons to be dissatisfied with the current > setup, a few of which are: > * Confluence as a product is no longer designed for our use case and our type > of content. > * 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 improve documentation except to point out > problems and hope someone else fixes them. > * 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. > I made a proposal in Aug 2016 ([email > link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E]) > to move the Ref Guide from Confluence to a new system that relies on > asciidoc-formatted text files integrated with the Solr source code. > This is an umbrella issue for the sub-tasks and related decisions to make > that proposal a reality. A lot of work has already been done as part of a > proof-of-concept, but there are many things left to do. Some of the items to > be completed include: > * Creation of a branch and moving the early POC work I've done to the project > * Conversion the content and clean up of unavoidable post-conversion issues > * Decisions about location of source files, branching strategy and hosting > for online versions > * Meta-documentation for publication process, beginner tips, etc. (whatever > else people need or want) > * Integration of build processes with the broader project > For reference, a demo of what the new ref guide might look like is currently > online at http://people.apache.org/~ctargett/RefGuidePOC/. > Creation of sub-tasks to follow shortly. -- This message was sent by Atlassian JIRA (v6.3.15#6346) - To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org For additional commands, e-mail: dev-h...@lucene.apache.org
[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide
[
https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15928580#comment-15928580
]
Cassandra Targett commented on SOLR-10290:
--
I've created a branch and added most of the files that existed in my POC github
repo. The branch is {{jira/solr-10290}}.
The new {{solr/solr-ref-guide}} directory contains the build scripts and tools,
as well as the source content and images. It can build the HTML files and/or
the PDF. The README explains a bit more about the directory structure and
dependencies required to do a build. PDFs can be built without anything locally
installed; the HTML needs a few things installed first. The source content is
from an export of Confluence done about a month ago, so be forewarned it's
slightly out of date.
The new {{solr/confluence-export}} directory includes all the tools used in the
conversion of the content from Confluence's HTML to Asciidoc format, plus the
post-conversion automated cleanup. Also included should be the raw export used
and files from intermediary steps in the conversion process, but I'm having
huge problems today with large uploads to ASF Git, so it will be a little bit
longer before I can get all that into the repo where it belongs. IOW, don't try
to use the conversion tools yet in case you were so inclined to do so.
The intent is that we'll get the content converted and then the
{{confluence-export}} directory will go away entirely so we won't need to carry
these tools around with us when this is merged to master.
> New Publication Model for Solr Reference Guide
> --
>
> Key: SOLR-10290
> URL: https://issues.apache.org/jira/browse/SOLR-10290
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
>Reporter: Cassandra Targett
>
> The current Solr Ref Guide is hosted at cwiki.apache.org, a Confluence
> installation. There are numerous reasons to be dissatisfied with the current
> setup, a few of which are:
> * Confluence as a product is no longer designed for our use case and our type
> of content.
> * 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 improve documentation except to point out
> problems and hope someone else fixes them.
> * 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.
> I made a proposal in Aug 2016 ([email
> link|http://mail-archives.apache.org/mod_mbox/lucene-dev/201608.mbox/%3CCAKrJsP%3DqMLVZhb8xR2C27mfNFfEJ6b%3DPcjxPz4f3fq7G371B_g%40mail.gmail.com%3E])
> to move the Ref Guide from Confluence to a new system that relies on
> asciidoc-formatted text files integrated with the Solr source code.
> This is an umbrella issue for the sub-tasks and related decisions to make
> that proposal a reality. A lot of work has already been done as part of a
> proof-of-concept, but there are many things left to do. Some of the items to
> be completed include:
> * Creation of a branch and moving the early POC work I've done to the project
> * Conversion the content and clean up of unavoidable post-conversion issues
> * Decisions about location of source files, branching strategy and hosting
> for online versions
> * Meta-documentation for publication process, beginner tips, etc. (whatever
> else people need or want)
> * Integration of build processes with the broader project
> For reference, a demo of what the new ref guide might look like is currently
> online at http://people.apache.org/~ctargett/RefGuidePOC/.
> Creation of sub-tasks to follow shortly.
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
