lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Grant Ingersoll <gsing...@apache.org>
Subject Documentation Brainstorming
Date Fri, 25 May 2007 21:10:01 GMT
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: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org


Mime
View raw message