Differences between revisions 5 and 6
Revision 5 as of 2007-06-09 08:15:14
Size: 2899
Editor: DoronCohen
Comment:
Revision 6 as of 2009-09-20 21:47:47
Size: 2913
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
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... 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...
Line 7: Line 7:
[[TableOfContents]] <<TableOfContents>>
Line 24: Line 24:
 * See [https://issues.apache.org/jira/browse/LUCENE-805 LUCENE-805]  * See [[https://issues.apache.org/jira/browse/LUCENE-805|LUCENE-805]]
Line 32: Line 32:
   * [https://issues.apache.org/jira/browse/LUCENE-765 index package - LUCENE-765]
   * [https://issues.apache.org/jira/browse/LUCENE-925 analysis package - LUCENE-925]
   * [https://issues.apache.org/jira/browse/LUCENE-926 document package - LUCENE-926]
   * [https://issues.apache.org/jira/browse/LUCENE-927 store package - LUCENE-927]
   * [[https://issues.apache.org/jira/browse/LUCENE-765|index package - LUCENE-765]]
   * [[https://issues.apache.org/jira/browse/LUCENE-925|analysis package - LUCENE-925]]
   * [[https://issues.apache.org/jira/browse/LUCENE-926|document package - LUCENE-926]]
   * [[https://issues.apache.org/jira/browse/LUCENE-927|store package - LUCENE-927]]
Line 38: Line 38:
 * "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 LUCENE-897]  * "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|LUCENE-897]]

Documentation Improvements

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

The origins of this page are this mailing list thread but people should feel free to add their own ideas...

Website

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 LUCENE-805

  • Most important part of this, I think is the "big picture" overview of why and when and how.

Javadocs

  • automated tools to help identify missing javadocs?
  • is there any way to easily allow annotation of javadocs (ala PHP and MySql)

  • Need package level docs for every package- see:
  • 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: 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?

Documentation_Improvements (last edited 2009-09-20 21:47:47 by localhost)