OK, so I have been really frustrated with the documentation of a
certain other open source project (a rather large and popular one)
that shall remain nameless, and it got me thinking about Lucene docs
and how we can improve them. Mind you, our docs are an order of
magnitude better than this other project (in its defense it has a lot
of dependencies and does not have as active a committer base as us)
So, this is an open call for ideas on how we can improve our docs.
Here are some areas I think need improving:
1. The demo/tutorial needs to be brought into the current Lucene
century. See https://issues.apache.org/jira/browse/LUCENE-805 Most
important part of this, I think is the "big picture" overview of why
and when and how.
2. There needs to be some docs that explain what analysis is at the
top level, similar to the current Scoring documentation.
3. A best practices page on the Wiki would be great.
4. The index package level javadocs are non-existent. See https://
issues.apache.org/jira/browse/LUCENE-765
5. Glossary of terms, etc.
Any others? Maybe we should start a wiki page that contains a list
of docs that need to be added/cleaned up and then we can work through
them a bit at a time? I know it isn't sexy, but it does bring a lot
of goodness to the project.
Ideas for how to do this:
1. Before doing a release, we have 1-2 weeks of code freeze, and we
focus on documentation and cleaning up bugs in JIRA.
2. Get the Hudson JIRA integration stuff hooked in so we can know if
patches are good faster, meaning we can turn around documentation
patches, and others, faster (not withstanding Otis' great turnaround
today on documentation patches)
3. There is a whole lot of knowledge stored in the email archives,
how can we leverage it?
Anyone else have ideas? Should we focus more on the wiki or the
committed docs? Is there a way we could let users annotate the
javadocs, wiki style? I know there are legal issues with user
contributions that are "released".
Cheers,
Grant
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
