Uploaded image for project: 'Solr'
  1. Solr
  2. SOLR-10290

New Publication Model for Solr Reference Guide

    XMLWordPrintableJSON

    Details

    • Type: Improvement
    • Status: Open
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: documentation
    • Labels:
      None

      Description

      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) 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.

        Attachments

        1. sitemap.patch
          4 kB
          Jan Høydahl
        2. sitemap.patch
          2 kB
          Jan Høydahl

          Issue Links

          1.
          Decide branching strategy for Ref Guide Sub-task Resolved Unassigned
          2.
          Decide online location for Ref Guide HTML pages Sub-task Resolved Cassandra Targett
          3.
          Convert existing Ref Guide and post-conversion cleanup Sub-task Resolved Cassandra Targett
          4.
          Resolve Ref Guide build errors Sub-task Open Unassigned
          5.
          Reduce size of new Ref Guide PDF Sub-task Resolved Unassigned
          6.
          Provide search for online Ref Guide Sub-task Open Unassigned
          7.
          Create meta-documentation on processes and policies to publish the Ref Guide Sub-task Resolved Cassandra Targett
          8.
          Create meta-documentation for how to write in asciidoc Sub-task Closed Cassandra Targett
          9.
          cleanup build.xml and ivy.xml related TODO items so they re-use lucene/solr variables/conventions Sub-task Resolved Chris M. Hostetter
          10.
          Clean up static page HTML top nav Sub-task Resolved Unassigned
          11.
          ref-guide "ant build-pdf" fails with jdk9 due to jigsaw blocking jruby Sub-task Open Chris M. Hostetter
          12.
          Consolidate font directories Sub-task Resolved Cassandra Targett
          13.
          Automate HTML builds via Jenkins to occur with each commit Sub-task Closed Steven Rowe
          14.
          Change Ref Guide site name at comments.apache.org for comment integration Sub-task Resolved Cassandra Targett
          15.
          Redirect Confluence pages to new HTML Guide Sub-task Resolved Chris M. Hostetter
          16.
          make ':toclevels:' work in our jekyll templates Sub-task Closed Chris M. Hostetter
          17.
          use more ant variables in ref guide pages: particular for javadoc & third-party lib versions Sub-task Closed Chris M. Hostetter
          18.
          CheckLinksAndAnchors should check for bogus page names / frags->anchors Sub-task Resolved Unassigned
          19.
          refactor duplicate ref guide content into "snippet" files that can be included Sub-task Open Unassigned
          20.
          differentiate DRAFT builds of the html/pdf ref-guides vs the official releases Sub-task Closed Chris M. Hostetter
          21.
          Remove unused theme files Sub-task Closed Cassandra Targett
          22.
          add license header to all adoc files Sub-task Closed Chris M. Hostetter
          23.
          fix/improve rat-sources and check-forbidden-api in solr-ref-guide Sub-task Open Uwe Schindler
          24.
          Should ref guide asciidoc files' line length be limited? Sub-task Resolved Steven Rowe
          25.
          Make Ref Guide PDF have same logo it used to have Sub-task Closed Cassandra Targett
          26.
          Remove feed.xml from HTML version of Ref Guide Sub-task Resolved Cassandra Targett
          27.
          create a link+anchor checker for the ref-guide that only depends on ivy resources Sub-task Closed Chris M. Hostetter
          28.
          Remove Confluence links from Javadocs, READMEs and example config files Sub-task Closed Cassandra Targett

            Activity

              People

              • Assignee:
                Unassigned
                Reporter:
                ctargett Cassandra Targett
              • Votes:
                2 Vote for this issue
                Watchers:
                8 Start watching this issue

                Dates

                • Created:
                  Updated: