lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Hoss Man (Confluence)" <>
Subject [CONF] Apache Solr Reference Guide > Internal - Maintaining Documentation
Date Fri, 12 Jul 2013 00:19:00 GMT
Space: Apache Solr Reference Guide (
Page: Internal - Maintaining Documentation (

Edited by Hoss Man:

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
 * 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
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|].  For example...

 * "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:
Change email notification preferences:


View raw message