Cassandra Targett created SOLR-10290:
----------------------------------------
Summary: 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: [email protected]
For additional commands, e-mail: [email protected]
