lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Busch <busch...@gmail.com>
Subject Re: Documentation Suggestion
Date Tue, 21 Jul 2009 23:17:18 GMT
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?

  Michael

On 7/21/09 5:57 AM, Grant Ingersoll wrote:
> One of the things that seems to work really well in Solr for 
> documentation is that people seem to be of the mindset that any time 
> some new feature is developed or a significant change is being made, a 
> Wiki page is added/updated.  I think this would be a really good habit 
> for us in Lucene to get in the habit of doing.   For instance, Jason 
> opened https://issues.apache.org/jira/browse/SOLR-1277 (ZooKeeper 
> integration for Solr) and I put up a patch and also started a Wiki 
> page on it: http://wiki.apache.org/solr/ZooKeeperIntegration.  We also 
> tend to do this in Mahout, too.  Now, going forward, those wanting to 
> understand how to use and install the patch can go to the wiki page 
> instead of just trying to figure out the patch.
>
> It has a few benefits I can think of:
>
> 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.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
>


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


Mime
View raw message