[Lucene-java Wiki] Update of "Documentation Improvements" by HossMan

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Lucene-java Wiki" for change notification.

The following page has been changed by HossMan:
http://wiki.apache.org/lucene-java/Documentation_Improvements

New page:
= Documentation Improvements =

A list of ideas (concrete or theoretical) on ways to improve documentation.

The origins of this page are [http://www.nabble.com/Documentation-Brainstorming-tf3818348.html#a10810352 this mailing list thread] but people should feel free to add their own ideas...

[[TableOfContents]]

= Website =

 * Need more obvious info for for people just getting started, both on http://lucene.apache.org and http://lucene.apache.org/java ... most stuff is hidden in left nav
   * where/how to download
   * getting started tutorial
 * Old news should be purged more often

= In Depth Docs on Key Concepts =

 * There needs to be some docs that explain what analysis is at the top level, similar to the current Scoring documentation.
 * Performance is another topic which would really benefit from a 'best practice' guide.

= Tutorial =

 * 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.

= Javadocs =

 * is there any way to easily allow annotation of javadocs (ala PHP and MySql)
 * Need package level docs for every package- see: https://issues.apache.org/jira/browse/LUCENE-765
 * Need class level docs for every public class
 * Need method level docs for every public method - particularly all methods used in any tutorial or "In Depth"  doc (ie: scoring.html, and any similar docs that get written)
 * "core plus contribs" nature of javadocs hard to understand for new users ... plethora of classes can be overwelming and hard to navigate - see: https://issues.apache.org/jira/browse/LUCENE-897
 * better auditing of all javadocs in a class needs to be done when applying patches (docs elsewhere in the class may refer to things that have changed)

= Wiki =

 * A best practices page on the Wiki would be great.
 * Glossary of terms, etc.

= Misc Process Issues =

 * Should we focus more on wiki docs or committed docs?
   * wiki is easier for community to contribute to
   * wiki pages can't be included in releases
 * Before doing a release, we have 1-2 weeks of code freeze, and we focus on documentation and cleaning up bugs in JIRA.
 * 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
 * How do we leverage vast amounts of info in mailing list archives?