james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Bagnara <apa...@bago.org>
Subject Re: [DISCUSS] Documentation as own project
Date Fri, 04 Mar 2011 13:31:04 GMT
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


Mime
View raw message