Mailing-List: contact java-dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: java-dev@lucene.apache.org
Received-SPF: pass (nike.apache.org: local policy)
Date: Tue, 21 Jul 2009 16:23:33 -0700 (PDT)
From: Chris Hostetter <hossman_lucene@fucit.org>
To: java-dev@lucene.apache.org
Subject: Re: Documentation Suggestion
In-Reply-To: <4A664C7E.5030007@gmail.com>
Message-ID: <Pine.LNX.4.64.0907211619100.5621@radix.cryptio.net>
References: <7B0CF000-0896-427B-B748-9B2C808F294A@apache.org>
 <4A664C7E.5030007@gmail.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII


: Couldn't we just update the description of the Jira issue itself so that it
: reflects the current state of the patch? Often the inital description of a
: Jira issue is never updated after the issue is created, even though the patch
: and goals changed as discussions happened. I think that would be more
: convenient than having in addition a wiki page?

That covers #1 of grants points, but not #2-4

for those not familiar with the process happening in solr, there isn't a 
seperate wiki page for every jira issue -- there is a seperate jira page 
for each major component/feature.  people submitting patches which add new 
functionality either write a new wiki page (if it's a radically new 
feature) or update an existing wiki page to include a new section which 
has a note inidcating the the documentation refers to uncommited changes 
pending a jira issue (and link to it).  When patches are finally 
committed, people remove the caveat warning form the wiki -- but even if 
they forget, someone else can notice later that the linked issue is 
resolved and remove it then.

the end result is documentation on features that lives long after the 
issue creating the feature goes away.

: > 1. Lengthy discussions in JIRA, while important, often become confusing to
: > come into later and to figure out what exactly is the state of the patch and
: > how it works
: > 2. We have real documentation on new features and existing features get
: > updated
: > 3. It forces the patch writer to explain the code, which often leads to
: > better code
: > 4. It lets others be involved in the documentation process.


-Hoss


---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org