On Mar 20, 2006, at 1:04 PM, Jukka Zitting wrote:
My guess is that the best way to handle this is to use Maven's
version of anakia to generate the site (for developers) but only
deploy a small subset of that to jackrabbit.apache.org (without
the reports, xref, etc.).
OK, I think that's reasonable. How about if we also generated static
javadoc and xref reports for each release? That should be good enough
for the occasional user.
From the perspective of one such (more) occasional user, I would not
want the main site to change between releases. Once jackrabbit 1.0 or
1.1 is released, I'm not likely to continue building from source. So
when I go to the jackrabbit.apache.org website, I expect to find the
docs (xref, javadocs, user documentation, etc.) for the current
release. If I'm downloading the binaries for jackrabbit, I should not
have to also download the source code for that version and run maven
to generate all the reports myself - that should be available to me
(assuming I'm using the current release) on the jackrabbit web site.
There are people who don't use maven themselves, and requiring them
to build the site on their own with a tool they would have to
download and install could be an "undue burden".
If the site were only generated once for each release, and that
generated site checked into subversion, it seems like that would
solve most of the issues. You can use the maven.xdoc.date and
maven.xdoc.version properties to place the date generated and version
of the software in the grey bar along the top, making it clear to
visitors what version of the documentation they're looking at. I
don't know how often user documentation (the FAQ, Getting Started,
First Hops, etc) needs to be updated between releases, but if it is
rare, it shouldn't be hard to regenerate the site, and only check in
the changed user docs.
Mark
