lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Grant Ingersoll <>
Subject Re: Lucene 2.2 soon?
Date Fri, 01 Jun 2007 20:51:05 GMT
On Jun 1, 2007, at 2:54 PM, Michael Busch wrote:

> On the other hand I'm not sure why we would need a code freeze. I  
> think
> it will take longer than just one or two weeks to improve the docs
> significantly. We should probably open some Jira issues for the
> different spots where we want to add documentation. That way we can
> track them separately and the different committers can assign those
> issues to them.

My thoughts are that by all of us agreeing to write docs, especially  
javadocs, for 1-2 weeks as part of a code freeze (at whatever level  
of commitment possible), we are far more likely to prioritize this  
work and make real headway.  The tendency is always to work on new  
features, etc. so I figured if we just set aside small chunks of time  
to bite off a small piece of the docs at a time we will get a lot  
further in this realm than if we feel like we have to get it all  
done.  I just know the tendency of all developers is to avoid docs  
and work on things that are more "interesting", so that is my  
rationale for  "docs week".

And this isn't just for our users.  There are a lot of significant  
changes being proposed (or already committed) to the merging/indexing  
process, and I know I, for one, would benefit from having a good,  
coherent, unbroken writeup of it in the javadocs  after the issues  
have been worked out.  While I understand the gist of most of what is  
being proposed via the emails, having it written down more formally  
would benefit us all in a way that the email discussions can not.  By  
doing this at release time, we can avoid the dreaded pain of  
constantly rewriting it as it is being developed.

As an aside, there are a few open issues already related to the index  
package and the demo/getting started page.

> After 2.2 is released we can start working then on an improved  
> website.
> I can tell you that I'm certainly motivated to improve our  
> documentation
> because I think we can have the best piece of software ever here,  
> but if
> we don't document and present if appropriately it is only half baked.
> Well, I don't mean that our docs are bad (especially compared to some
> other projects), but there's certainly room for improvements.

I am more concerned w/ the Javadocs at this point than the website,  
mostly b/c I think the website is a major undertaking (not that I am  
discouraging working on it), at least the part about writing a good  
tutorial and getting started page, but maybe I am wrong.  I know that  
writing the scoring.html page was a significant undertaking for me  
and doing a similar page for indexing/analysis will likely be the same.


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message