portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Sean Taylor <da...@bluesunrise.com>
Subject Re: [PROPOSAL] Move to confluence and cwiki for project website and documentation
Date Tue, 04 Mar 2008 23:41:29 GMT
All the x-posting confuses me.
Now that everyone is aware of the proposal, can we discuss this on  
general?

I like the idea of using Confluence. In general I am +1.
Just a few questions, which I will ask on general...


On Mar 4, 2008, at 2:42 PM, Ate Douma wrote:

> 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:
>   http://cwiki.apache.org/CWIKI/
>
> The Geronimo and Wicket projects have some nice additional  
> documentation how they make use of this:
>   http://cwiki.apache.org/geronimo/geronimo-cwiki-documentation- 
> architecture.html
> and
>   http://wicket.apache.org/writing-documentation.html
>
> 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
>

-- 
David Sean Taylor
Bluesunrise Software
david@bluesunrise.com
[office] +01 707 773-4646
[mobile] +01 707 529 9194





Mime
View raw message