james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Eric Charles <e...@apache.org>
Subject Re: [DISCUSS] Documentation as own project
Date Fri, 04 Mar 2011 13:45:27 GMT
Hi,

The 2.2 doc is no more viewable on the web site.
To follow current structure, could we create a 2.2 module somewhere 
under https://svn.apache.org/repos/asf/james/server/ branches/2.2 or 
tags/2.2 and move the doc there ?

We certainly should also have a look at the future CMS that we'll have 
to use but I think that confluence is no more the way to go.

Maybe dev docs could remain in the module, but I still fell there's a 
need for simple end-user documentation.

To be continued :)

Eric

On 4/03/2011 14:31, Stefano Bagnara wrote:
> 2011/3/4 Felix Knecht<felix@otego.com>:
>> Hi all
>>
>> Starting by trying to figure out the main structure of projects in JAMES and
>> trying to update the maven-skin of JAMES I realized, that IMO generating
>> documentation needs some more attention. I'd like to do this.
>>
>> ATM we have several place where documentation exists in svn. In the
>> "project" project exist documentation about the project and about the server
>> but not about all other projects like imap, protocols, etc. They have there
>> documentation in their own project. Looks not very logic - why does the
>> server docs are in projects project?
> James 2.2 and older have documentations and they was not maven based.
> So, in order to publish "legacy" docs we decided to put them in the
> "project" project.
> So, they are there only because there was no better place.
>
>> Apart of the logic there's another problem:
>> Maven can generate a lot of reports. Some (like findbugs, pmd, emma, ...)
>> are very usefull for code review. They aren't generated yet... but they will
>> at least in the navigation structure 'pollute' a plain documentation site.
>>
>> Here's what I suggest:
>> Create a new project "documentation" and put all documentation (not reports)
>> of all projects into this one. It's structure could look like
>>
>> /documentation
>>   /server
>>   /server-2.2.0
>>   /imap
>>   /protocols
>>   / ...
>>
>> I'm not sure but I think we can even don't need the branches/tags/trunk
>> folders in /documentation.
>>
>> Then cleanup all projects from documentation left over and let them create
>> specific reports we wanted to use for code review in a multi-module manner.
>> These reports can be generated by Jenkins CI on a daily/weekly(?) base to
>> have them available when needed. We can then also have a link in the
>> documentation about the reports generate from trunk if wanted.
>>
>> Deploying documentation will still be done as it is by manual deployment to
>> people.apache.org.
>>
>> WDOT?
> I don't like this too much. If we don't keep documentation inside each
> project then I would simply move documentation process to confluence
> that is much easier to mantain.
>
> Moving the documentations to its own maven projects sounds like the
> worst of the solutions, to me.
>
> What are the advatages of a maven based documentation project istead
> of using Confluence?
>
> Stefano
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
> For additional commands, e-mail: server-dev-help@james.apache.org
>


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


Mime
View raw message