jackrabbit-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Alexander Klimetschek" <aklim...@day.com>
Subject Documentation
Date Fri, 20 Jun 2008 14:27:04 GMT
Hi all,

I was thinking about a simple way to create a better documentation for
Jackrabbit. Currently there is some stuff on the website (I think
largely thanks to Jukka!) and some snippets about clustering and
datastore on the wiki. But many things are missing, also for some very
basic descriptions. One can see that by the type of questions coming
up on the users list.

One important thing that we will have available soon is a nice HTML
version of the JCR spec, which will be hosted on dev.day.com (I
mistakenly tried to put it on the jackrabbit site, which is not
allowed by the spec license), so we can link to it. This should give
the JCR concepts a much better visibility, since many people don't
want to download the pdf spec from a different site and are propably
scared to read a boring, excessively long document (which the JCR spec
is not at all!).

The other thing is that we should
- sort the current documentation (have an index, so people know where
to start and look for things)
- add more (especially basic stuff) - the hard part ;-)
- provide a separate documentation section per release (1.4, 1.5)
- and package the documentation with the release binaries

I think the most simple solution would be to use the "site source"
wiki (http://cwiki.apache.org/confluence/display/JCR), as it is done
now, but have a separate subsection for each release (eg.
documentation/1.4). Upon a new release, the documentation of the old
version can be copied and modified according to new features etc. The
free wiki (http://wiki.apache.org/jackrabbit/) should be reduced to
annotations, ongoing faqs, etc., where everyone, not only the
committers, can write to.

I would do the work of structuring the docs, gathering the information
from the wiki and write some basic things. But I would be very happy
if everyone could write a bit on the specific system parts they have
written or worked on! WDYT?

Regards,
Alex

-- 
Alexander Klimetschek
alexander.klimetschek@day.com

Mime
View raw message