Return-Path: Delivered-To: apmail-portals-jetspeed-dev-archive@www.apache.org Received: (qmail 32346 invoked from network); 4 Mar 2008 23:42:07 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 4 Mar 2008 23:42:07 -0000 Received: (qmail 25153 invoked by uid 500); 4 Mar 2008 23:42:02 -0000 Delivered-To: apmail-portals-jetspeed-dev-archive@portals.apache.org Received: (qmail 25127 invoked by uid 500); 4 Mar 2008 23:42:02 -0000 Mailing-List: contact jetspeed-dev-help@portals.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Jetspeed Developers List" Delivered-To: mailing list jetspeed-dev@portals.apache.org Received: (qmail 25112 invoked by uid 99); 4 Mar 2008 23:42:02 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 04 Mar 2008 15:42:02 -0800 X-ASF-Spam-Status: No, hits=2.0 required=10.0 tests=HTML_MESSAGE,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: local policy) Received: from [216.23.125.30] (HELO scriptall.com) (216.23.125.30) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 04 Mar 2008 23:41:25 +0000 Received: (qmail 4988 invoked by uid 509); 4 Mar 2008 18:41:38 -0500 Received: from 75.32.148.169 by edison (envelope-from , uid 507) with qmail-scanner-1.25-st-qms (clamdscan: 0.87/2439. spamassassin: 3.1.7. perlscan: 1.25-st-qms. Clear:RC:1(75.32.148.169):. Processed in 1.169109 secs); 04 Mar 2008 23:41:38 -0000 X-Antivirus-MYDOMAIN-Mail-From: david@bluesunrise.com via edison X-Antivirus-MYDOMAIN: 1.25-st-qms (Clear:RC:1(75.32.148.169):. Processed in 1.169109 secs Process 4968) Received: from adsl-75-32-148-169.dsl.pltn13.sbcglobal.net (HELO [192.168.3.101]) (75.32.148.169) by scriptall.com with SMTP; Tue, 04 Mar 2008 18:41:37 -0500 In-Reply-To: <47CDD04A.2070809@douma.nu> References: <47CDD04A.2070809@douma.nu> Mime-Version: 1.0 (Apple Message framework v753) Content-Type: multipart/alternative; boundary=Apple-Mail-32-881106505 Message-Id: <4B71D490-8C10-4019-8086-987A0EA20AD6@bluesunrise.com> Cc: Jetspeed Developers List , Bridges Developers List , Portals PMC From: David Sean Taylor Subject: Re: [PROPOSAL] Move to confluence and cwiki for project website and documentation Date: Tue, 4 Mar 2008 15:41:29 -0800 To: pluto-dev@portals.apache.org X-Mailer: Apple Mail (2.753) X-Virus-Checked: Checked by ClamAV on apache.org --Apple-Mail-32-881106505 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=UTF-8; delsp=yes; format=flowed All the x-posting confuses me. Now that everyone is aware of the proposal, can we discuss this on =20 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 =20 > other sibling projects, Pluto and Bridges, as well as our PMC as I =20 > think it might be of interest to the whole Portals community. > > For now though, my proposal only targets the Jetspeed project web =20 > site, and I'd like to hear who might be interested in this . > > Until now, we've been defining our jetspeed website and =20 > documentation in (Maven-1) xdoc format, which makes it possible to =20 > maintain it in the svn repository, and more or less "seemingly" =20 > integrate project meta-data and end user documentation in one =20 > central location to be pushed out (after generation) as our primary =20= > project website and documentation. > > While this more or less works "ok", as we all know, maven site =20 > generation has it peculiar quirks, and quite strict (and limiting) =20 > rules to obey to get it working correctly. > > Furthermore, although the goal of maintaining the documentation =20 > definitions versioned in svn by itself doesn't seem like a bad =20 > idea, in practice this poses logical problems once a "release" tag =20 > has been set. Most commonly, the website documentation is in need =20 > of updating/correcting for an already released version, so changes =20 > usually are committed against the svn trunk which might already be =20 > (way) ahead in development. > > One solution would be to maintain separate "documentation update" =20 > branches in svn, but that's cumbersome too to say the least. > > On top of that, it is very difficult (and very impractical) to =20 > maintain online documentation for multiple release versions, while =20 > end users most likely will be using different/older version(s) than =20= > just the current (trunk) development version. > > And maintaining the maven site documentation in xdoc (or apt or =20 > even some more exotic) format is in practice, in my personal view, =20 > horrible to do. > AFAIK, there still isn't any good GUI support for writing this but =20 > using plain ASCII or XML format, and using and maintaing correct =20 > anchors and image references without any proper (direct) feedback =20 > mechanism is quite error prone. For some this might be the perfect =20 > tool, but in my personal experience, these limitations have =20 > hindered us (as project committers) very much in writing and =20 > providing some good and proper documentation. > Writing documentation usually already isn't the best quality of us =20 > coders (certainly not mine), but having to do so in maven site =20 > format definitely doesn't help. > > Finally, although we have a MoinMoin Wiki for Jetspeed-2 too (see: =20 > http://wiki.apache.org/portals/jetspeed2) which can be used by both =20= > the committers and other community members to provide more direct =20 > and interactive documentation, in reality hardly anyone uses it, is =20= > (in my view) ugly and difficult to use, and contains mostly stale/=20 > outdated information. > > And now, with our recent restructuring of our svn by moving the j2-=20 > admin and other portlet applications to a separate applications =20 > root folder so they now will have their own life cycle, even more =20 > complex challenges arise. Maintaining and *integrating* two or even =20= > more maven generated websites under one primary site is definitely =20 > not going to be easy (forget about maintaining documentation for =20 > multiple releases) ... > > As we now are working on a major overhaul of the Jetspeed-2 build =20 > system (dropping the old maven-1/2 structure and replacing it with =20 > a clean maven-2 project rewrite from scratch), maybe this now also =20 > is the right time to evaluate our current project documentation and =20= > website generation solution. > > And as probably already obvious from my above "rant" against our =20 > current solution, I'd like to propose something completely different. > > Since quite some time, several other Apache projects have moved to =20 > Confluence for their documentation tasks *and* their project =20 > 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 =20 > static HTML site snapshot can automatically be created (after each =20 > change or update) and used as basis for a Apache project website. =20 > Additionally, Velocity scripts can be run during the export to =20 > provide additional formatting for a custom styled website. > > Although I could try to describe here all the procedures and =20 > possibilities of this solution and the benefits it brings, I think =20 > it better to read up on these yourself and also see how these other =20= > 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 =20 > documentation how they make use of this: > http://cwiki.apache.org/geronimo/geronimo-cwiki-documentation-=20 > 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 =20 > documentation for jetspeed-2, j2-admin and future products > - also allow selected end users (non-committers but with a CLA on =20 > file, see main CWIKI documentation for explanation) > to maintain these official documentation spaces > - also switch to using Confluence for our public jetspeed-2 wiki =20 > (replacing MoinMoin) for additional non-official/endorsed project =20 > information > - integrate all the above in one new main cwiki based jetspeed-2 =20 > project website > > WDYT? > > Regards, > > Ate > --=20 David Sean Taylor Bluesunrise Software david@bluesunrise.com [office] +01 707 773-4646 [mobile] +01 707 529 9194 =EF=BF=BC --Apple-Mail-32-881106505 Content-Type: multipart/related; type="text/html"; boundary=Apple-Mail-33-881106505 --Apple-Mail-33-881106505 Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=ISO-8859-1
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/p= ortals/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:
=A0 Cayenne =A0 - http://cayenne.apache.org
=A0 = Directory - http://directory.apache.org=
=A0 = Felix =A0 =A0 - http://felix.apache.org
=A0 = Geronimo=A0 - http://geronimo.apache.org
=A0 = James =A0 =A0 - http://james.apache.org
=A0 = Wicket=A0 =A0 - 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:
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)
=A0 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?


Ate


--=A0
David Sean = Taylor
Bluesunrise Software
[office] +01 707 773-4646
[mobile] +01 707 529 9194


 =

= --Apple-Mail-33-881106505 Content-Transfer-Encoding: base64 Content-Id: <354D5BAC-9F17-4128-8311-CFA687780F61@local> Content-Type: image/jpeg; x-unix-mode=0644; name=bsr.jpg Content-Disposition: inline; filename=bsr.jpg /9j/4AAQSkZJRgABAQEAYABgAAD//gAcU29mdHdhcmU6IE1pY3Jvc29mdCBPZmZpY2X/2wBDAAoH BwgHBgoICAgLCgoLDhgQDg0NDh0VFhEYIx8lJCIfIiEmKzcvJik0KSEiMEExNDk7Pj4+JS5ESUM8 SDc9Pjv/2wBDAQoLCw4NDhwQEBw7KCIoOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7 Ozs7Ozs7Ozs7Ozs7Ozs7Ozv/wAARCAAYAHUDASIAAhEBAxEB/8QAGgABAQADAQEAAAAAAAAAAAAA AAQDBQYBB//EADEQAAEDAwMDAgQEBwAAAAAAAAECAwQABRESITEGE0EUUSJhcYEHFUKRFiMyUnKh sf/EABgBAQEBAQEAAAAAAAAAAAAAAAABAgME/8QAHxEAAwEAAQQDAAAAAAAAAAAAAAECERIDITFB UeHw/90ABAAo/9oADAMBAAIRAxEAPwD6zc5K4VskyWwCpppS0hXBIGahidTW5yGy9IlNtqWhJWQD pSryM/Wrbsw5JtMuO0nU46ypCRxkkEVqI5vEe1s202VpagyGy4Xk9rjG45rrKlyea6tX28Z8F8q5 rZvFtitBtTMwOEqzv8IBGP3q5uXHdacdbdSpDZKVkeCOR9q0LdjmQF2YtH1SYPcS6SrScL9s+B/w US1d4TcyCzbkvpfccW2+HglICsncHfP0o5l5jMz1LTfJfsX2bl66wI7DT7sltLbwy0c5K9s7DzSL dYU0qSxISpaRlSCClQHvg1oJVinqjWp5oK7sJjtusod0Kzgf0q4zmststUp24omyo8lospUlHqJI WSSMYwkY0/fkVeE5ulXV6rrOJdG6pscuWiKxcG1uOKKWzghK1b7JURgnY7A+KvjT4szvemfQ76dw tO6f0LHIPzri7fab5Alx2IcF22RWHwt8OzEvRA2DlXbSr4kk5O+2N/er4jF7sU65MxrSmczcJS5L chMhKEt6gBhYO/jkZqVE+md1T03H8UWMRI8v8zY7EkqSyvOzhScED3IO1ZbffbZdFOIhy0uONAKW 2oFKkj3KTg4rkunulbpBjdMIlx0A296UuQNYIRrKigj35HHFb1y1S1dcKuYaHpjbDHDmoZ7mvOMc 8VbiE8TKnT8mK43qLcoSzary20Y4D7r2hRb0DkFWNvtvVKepbZGhxjMuTLjj7aXUlhClBSFcKAGS B8zULdmmtfhw5aRGxLMVaO0lQ3Uc+eN81qxY7nCt9qWi0y1S2be1HW7AnJadSpKd0LCvhKc+Rmrk 5m+zOd+R17l9tTNvanrnsemewGnArIWTwE45ry3322XR1TUSUlbqRqU2oFCwPfSQDjauVndM9QSo VlmSHkPXC3FwvNx3AyVhX9igMBQHy3qmy2SdJvcW53CHOjmIlegzJ4eXlQxgBIxjnk+BtWXE55Km 9OzpSlcjZgkxhJjuMqWpIWMZTyK1jnTTDq8rmSsdjs4S5pJ2UM5H+RwOBt7ClKEK2bS0w+3IDry3 UNpbKlLzqAzyOP1f6FSnpqMXQ4ZczZ9T2kO4GSpKtPyTlI2+vuaUoNMLHSMNkHMua7/LW2nuPE4C koTn5kBAwT7k8mr4tobiy1SRIfcUpsIKFqykbAEgeM6Rxt+9KUKQO9IxHYXpFzJhbLTjR1OA7L1D yPAWcfbnFXqtKFIW36h7QpxDiU5HwFJzgHHBPOffbFKUBhT09GBwp59bfYDJQpfKRjzz4qlm2NsT fUoedwGg0loq+AAHOce9KUBXimKUoD3GaAYpSgPaUpQH/9k= --Apple-Mail-33-881106505-- --Apple-Mail-32-881106505--