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.
Cheers,
Grant
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
