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