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-unsubscr...@lucene.apache.org
For additional commands, e-mail: java-dev-h...@lucene.apache.org
