lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Doron Cohen <DOR...@il.ibm.com>
Subject Re: site javadocs and resolved issue 678
Date Tue, 31 Oct 2006 22:11:02 GMT
Things get complicated because of relations/links between javadocs and
other documentation.

1. Site documentation is generated as part of Lucene build, and is
versioned with Lucene.
2. Wiki documentation is not versioned with Lucene, and unrelated to the
build.
3. Improvements to documentation would be nice to have in the public site
(e.g. scoring) even before released.
4. Documentation changes e.g. file-format, query syntax - would be quite
confusing to have in the public site before released, unless it is clearly
stated that "this is for most current build" and online documentation for
past releases is available elsewhere.

How about adding to the left navigation bar, under Resources, a bullet
saying "All Releases Docs" which would take to a (new) Wiki page, - that
page would explain that while the main site online documentation relates to
the most current build, an online documentation of published releases is
available either by downloading that release (link to download) or by
navigating to an online (new) copy of the documentation for that release.
Whenever a new release is closed that Wiki page should be updated. Next
release (2.1?) when closed would contain a link to the same Wiki page but
online docs for past releases (2.0 and under) would not, but this is ok I
think.

The docs of recent build and of past releases should contain the build info
- javadocs do already - saying for current 2.1 seems ok, perhaps saying
nightly build (date) is clearer.

This would allow to maintain coherence between all online docs. (But would
it be a little harder for new users to realize that docs they see in the
main site do not relate to the most recent release?)

Do you think this makes sense? Worth the maintenance burden?

If so I can create the Wiki page and patch xdocs as outlined. But I do not
have knowledge/permission to put past releases docs in the Web site (this
would be required).

- Doron

Sami Siren <ssiren@gmail.com> wrote on 31/10/2006 08:28:07:
> Doug Cutting wrote:
> > Actually the've typically been the current release.  Hadoop updated its

> > javadocs nightly before its first release, but now they're the current
> > release.  Solr may update it's nightly, but then it doesn't yet have
any
> > releases.  And Nutch and Lucene's hosted javadocs are traditionally the

> > most recent release.
>
> Nutch currently hosts plenty of javadocs - latest nightly build, latest
> release from 0.8.x branch and latest release from 0.7.x branch.


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