[SOLR-10290] New Publication Model for Solr Reference Guide - ASF JIRA
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/.
Read full article from [SOLR-10290] New Publication Model for Solr Reference Guide - ASF JIRA
No comments:
Post a Comment