[jira] [Commented] (SOLR-10290) New Publication Model for Solr Reference Guide

["Christine Poerschke (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/SOLR-10290?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=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-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org