karaf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jean-Baptiste Onofré ...@nanthrax.net>
Subject Re: Karaf first birthday concall minute notes
Date Fri, 17 Jun 2011 08:36:59 GMT
Hi Christian,

I have no problem to discuss about that and submit to a vote.

First, a quick history about that :)

On both Karaf and ServiceMix, we had (and still have) documentation 
requirements with a multi-format outputs (PDF, HTML) and professional 
look'n feel.
Another requirement is to be able to "link" the documentation with a 
specific Karaf version. The documentation could be widely different 
between Karaf 2.1.x and Karaf 3.0.x for instance.

Starting with these requirements, we discussed around:
1/ usage of the Apache confluence wiki to store the documentation and 
use of an "external" tool (such as Prince) to extract content from the 
wiki and generate the document output (PDF). It looks like the way it 
does in Camel.
2/ usage of DocBook directly into the Karaf svn repo
3/ usage of Scalate directly into the Karaf svn repo

Here's the conclusions that we had regarding the previous points:
1/ it seems that the Apache confluence wiki future is not really clear. 
There were discussion around Apache CMS, cwiki EOL, etc.
If we "invest" a lot in the documentation on the wiki, it could "cost" a 
lot very soon depending of the cwiki future. That's why we voted to not 
use directly cwiki.
2/ DocBook is XML document, very rich namespace but no always easy (I 
don't say that as I love DocBook but it's the feedback that we got ;)).
3/ Scalate documentation was the choice because the syntax is really 
close to wiki and the mechanism is like DocBook document generation. So 
it's like a solution in the middle.

To be honest, I was more on 2/ or 3/ at the beginning. But, when I see 
the Camel documentation and website, I'm quite around to revert my point 
of view ;). It's clear that Karaf (and ServiceMix, that's why I added 
ServiceMix dev mailing list in copy of this e-mail) documentation and 
website could be managed in the same way that Camel does.

My only concern is that we decide to move back to cwiki (I don't mind to 
make the effort, I will do it), we need to have a clear view about the 
cwiki future and relationship with Apache CMS.

I'm sure that the ASF members could provide us more information: 
@gnodet, @dkulp ?

Regards
JB


On 06/17/2011 10:19 AM, Christian Schneider wrote:
> I know that I have proposed this before and then got the answer that
> this was discussed already. Still I have the feeling that everybody
> dislikes the current way we build our website.... so again a try :-)...
>
> I would even go a step farther and do as much of the website on the wiki
> as possible. Dan Kulp has written an exporter script that syncs the wiki
> to static pages so the admins can live with it.
>
> I think we have to try to make the website and documentation as open as
> possible. The wiki allows us to give editing right to anyone with a
> valid icla. That is much more accessible than the current site.
> Additionally any change can be seen right after the change on the wiki.
> I think that is a big motivation. Currently you have to submit a patch
> for the website and wait for someone to commit it and then for someeone
> else to sync it to the web. This process can take months sometimes. That
> is quite frustrating and I am sure it is the reason why we have so few
> updates to the site and documentation.
> Another nice thing of the wiki is that it is a first step of
> contribution below submitting patches. So people can come in contact
> with the project gradually.
>
> Of course the wiki has the problem that it is not synched to the
> releases but in cxf and camel this is also not the case. Still it works
> well there. The way to couple the documentation to releases is to note
> for example which attribute of a command has been introduced in which
> version. This is niot perfect but works quite well in practice.
>
> Christian
>
>
> Am 17.06.2011 09:46, schrieb Jean-Baptiste Onofré:
>> Agree Andreas,
>>
>> I think that:
>> - link to the wiki "cap" page in the community area of the website
>> - wiki pages as children of the "cap" page
>>
>> is the most efficient way.
>>
>> Regards
>> JB
>

Mime
View raw message