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:
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:
and
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
WDYT?
Regards,
Ate
