portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ate Douma <...@douma.nu>
Subject [PROPOSAL] Move to confluence and cwiki for project website and documentation
Date Tue, 04 Mar 2008 22:42:18 GMT
Dear community,

I'm cross-posting this proposal to the developers lists of our other sibling projects, Pluto
and Bridges, as well as our PMC as I think it might be of interest 
to the whole Portals community.

For now though, my proposal only targets the Jetspeed project web site, and I'd like to hear
who might be interested in this .

Until now, we've been defining our jetspeed website and documentation in (Maven-1) xdoc format,
which makes it possible to maintain it in the svn repository, 
and more or less "seemingly" integrate project meta-data and end user documentation in one
central location to be pushed out (after generation) as our primary 
project website and documentation.

While this more or less works "ok", as we all know, maven site generation has it peculiar
quirks, and quite strict (and limiting) rules to obey to get it 
working correctly.

Furthermore, although the goal of maintaining the documentation definitions versioned in svn
by itself doesn't seem like a bad idea, in practice this poses 
logical problems once a "release" tag has been set. Most commonly, the website documentation
is in need of updating/correcting for an already released version, 
so changes usually are committed against the svn trunk which might already be (way) ahead
in development.

One solution would be to maintain separate "documentation update" branches in svn, but that's
cumbersome too to say the least.

On top of that, it is very difficult (and very impractical) to maintain online documentation
for multiple release versions, while end users most likely will be 
using different/older version(s) than just the current (trunk) development version.

And maintaining the maven site documentation in xdoc (or apt or even some more exotic) format
is in practice, in my personal view, horrible to do.
AFAIK, there still isn't any good GUI support for writing this but using plain ASCII or XML
format, and using and maintaing correct anchors and image references 
without any proper (direct) feedback mechanism is quite error prone. For some this might be
the perfect tool, but in my personal experience, these limitations 
have hindered us (as project committers) very much in writing and providing some good and
proper documentation.
Writing documentation usually already isn't the best quality of us coders (certainly not mine),
but having to do so in maven site format definitely doesn't help.

Finally, although we have a MoinMoin Wiki for Jetspeed-2 too (see: http://wiki.apache.org/portals/jetspeed2)
which can be used by both the committers and other 
community members to provide more direct and interactive documentation, in reality hardly
anyone uses it, is (in my view) ugly and difficult to use, and 
contains mostly stale/outdated information.

And now, with our recent restructuring of our svn by moving the j2-admin and other portlet
applications to a separate applications root folder so they now will 
have their own life cycle, even more complex challenges arise. Maintaining and *integrating*
two or even more maven generated websites under one primary site is 
definitely not going to be easy (forget about maintaining documentation for multiple releases)

As we now are working on a major overhaul of the Jetspeed-2 build system (dropping the old
maven-1/2 structure and replacing it with a clean maven-2 project 
rewrite from scratch), maybe this now also is the right time to evaluate our current project
documentation and website generation solution.

And as probably already obvious from my above "rant" against our current solution, I'd like
to propose something completely different.

Since quite some time, several other Apache projects have moved to Confluence for their documentation
tasks *and* their project website "generation".
Some good and also very nice *and* different looking examples are:
   Cayenne   - http://cayenne.apache.org
   Directory - http://directory.apache.org
   Felix     - http://felix.apache.org
   Geronimo  - http://geronimo.apache.org
   James     - http://james.apache.org
   Wicket    - http://wicket.apache.org
and there are several more.

Although Confluence is a real wiki, with an AutoExport plugin a static HTML site snapshot
can automatically be created (after each change or update) and used as 
basis for a Apache project website. Additionally, Velocity scripts can be run during the export
to provide additional formatting for a custom styled website.

Although I could try to describe here all the procedures and possibilities of this solution
and the benefits it brings, I think it better to read up on these 
yourself and also see how these other projects are using it.

The primary documentation can be found here:

The Geronimo and Wicket projects have some nice additional documentation how they make use
of this:

My proposal is simple:
- switch to using this Confluence+cwiki solution
- maintain separate Confluence spaces for release specific documentation for jetspeed-2, j2-admin
and future products
- also allow selected end users (non-committers but with a CLA on file, see main CWIKI documentation
for explanation)
   to maintain these official documentation spaces
- also switch to using Confluence for our public jetspeed-2 wiki (replacing MoinMoin) for
additional non-official/endorsed project information
- integrate all the above in one new main cwiki based jetspeed-2 project website




To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org

View raw message