Mailing-List: contact commits-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@lucene.apache.org
Date: Fri, 12 Jul 2013 00:19:00 +0000 (UTC)
From: "Hoss Man (Confluence)" <confluence@apache.org>
To: commits@lucene.apache.org
Message-ID: <1222903388.4886.1373588340007.JavaMail.confluence@cwiki-vm>
Subject: [CONF] Apache Solr Reference Guide > Internal - Maintaining
 Documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Auto-Submitted: auto-generated

Space: Apache Solr Reference Guide (https://cwiki.apache.org/confluence/display/solr)
Page: Internal - Maintaining Documentation (https://cwiki.apache.org/confluence/display/solr/Internal+-+Maintaining+Documentation)


Edited by Hoss Man:
---------------------------------------------------------------------
{toc}

h1. How This Documentation is Managed & Released

This CWIKI Space is used to continually maintain live documentation about the _next_ feature Apache Solr release that will be created off of the current "stable" branch (ie: as of July 2013, the "stable" branch is "branch_4x" and the next feature release will be "4.4.0").  

At any point during development, documentation can (and should) be added to this space to match changes made to the code on the stable branch.  If changes are made to the "trunk" branch which are not back-ported to the stable branch, those should be noted on the [Internal - Trunk Changes to Document] page for inclusion in the documentation once the stable branch changes (ie: when "branch_4x" is retired and "branch_5x" is created)

Around the time that a feature release (ie: 4.4.0, 4.5.0, etc...) is made from the stable branch, [this documentation should be published as a PDF and voted on as a documentation release|Internal - How To Publish This Documentation].  This doesn't necessarily need to happen in lock step with the code release, it may be advantageous to wait until the code release vote is final before creating the PDF, as people may find improvements/mistakes in the documentation.

If mistakes are found in the documentation after being officially released, they should be noted on the [Errata] page.  Each mistake should be noted redundantly in a section for each version of the documentation that contained the error.

When bug fix releases (ie: 4.4.1, 4.4.2) of Apache Solr are released, updates to the [Errata] page may be prudent, however there should _not_ be a corresponding release of the documentation since:
 * Bug fix releases should not contain any new features, so there should be nothing significant to document
 * The "live" copy of the documentation in Confluence will most likely already have updates for the next feature release which should not be mistakenly published

h1. Who Can Edit This Documentation

This Confluence wiki Space can be edited by any Lucene/Solr committer once they have a [Confluence account|https://cwiki.apache.org/confluence/login.action?os_destination=%2Fdashboard.action] and have a Confluence Admin [grant them the necessary ACLs|Internal - CWIKI ACLs].  Any PMC member willing to help volunteer to help maintain the CWIKI instance may [get Confluence Admin ACLs|Internal - CWIKI ACLs].

h1. How to Give Feedback on This Documentation

Users who do not have the necessary ACLs to edit this Space may still use the comments feature at the bottom of any page to suggest additions, improvements, or point out any mistakes -- a Confluence login is the only thing required to post comments.  Comments are _not_ included in the exported PDF.
 
If/When feedback from a comment is incorporated into the appropriate page, the comment may be deleted by a Space Admin to help track what suggestions have already been incorporated and to minimize noise/distractions.

People with broader questions/concerns about the documentation as a whole are encouraged to start a thread on the solr-user mailing list.

h1. What Should and Should Not be Included in This Documentation

This Space (and the resulting PDF export that we publish) should contain any and all "official" documentation about Apache Solr.  It is the definitive "User Reference Guide" as published/released by the ASF and the Lucene PMC.

Bottom line: *If there is a feature in Apache Solr, then it should be mentioned in this documentation, along with the details of what it does, how to configure it, and how to use it.*

Some types of documentation however may not make sense to live in this "User Reference Guide" and should instead live (forever) in the less formal (and not officially published as a release) [Community Wiki|http://wiki.apache.org/solr/].  For example...

 * http://wiki.apache.org/solr/FAQ
 * http://wiki.apache.org/solr/Support
 * http://wiki.apache.org/solr/PublicServers
 * http://wiki.apache.org/solr/SolrPerformanceData
 * http://wiki.apache.org/solr/HowToContribute
 * http://wiki.apache.org/solr/NightlyBuilds
 * http://wiki.apache.org/solr/Support
 * http://wiki.apache.org/solr/CommitterInfo
 * "Tips and Tricks" style advice on using/abusing features
 * "Case Study" type pages created by users to showcase their usage/experiences

h2. Migrating "Official" Documentation from MoinMoin

Practically speaking, there is currently (as of July 2013) a lot of content on the "Community Wiki" (aka: MoinMoin) that should belong in this Ref Guide.  As time permits, people should make efforts to migrate the portions of that wiki content into this documentation when appropriate, but leave stub versions of the existing MoinMoin pages (with their existing page sections) intact with new links to the appropriate (new) pages in this confluence space:
 # The existing pages, and relative anchors in those pages, are heavily linked to from across the web and we should do what we can to help people following those links find the new location for the content.
 # The existing pages can and should still serve as a place for the user community as a whole to post their tips & tricks about using the various features


Stop watching space: https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=solr
Change email notification preferences: https://cwiki.apache.org/confluence/users/editmyemailsettings.action