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 14:07:12 GMT
2011/3/4 Eric Charles <eric@apache.org>:
> Hi,
>
> The 2.2 doc is no more viewable on the web site.

>From here you still can go to the 2.2.0 folder:
http://james.apache.org/server/archive/document_archive.html

> 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 ?

I don't see the point in creating a 2.2 branch and upgrading it to
maven in order to be able to move the docs there. If you want to
create a new project to host legacy documentation then please don't
call it server/branches/2.2 as people expect to find the 2.2 code
there.

The 2.2.0 folder takes just the 0.5% of website traffic recently, IMO
we can even remove it from the website. 2.3 docs will need their place
for a lot, instead.

> 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.

Can I ask why? Trying to make a list of pro/cons of using Confluence
instead of a maven project used just for documentation I can't
identify many "pro" for maven based docs: the only pro I had was that
they was distributed together with project sources, but if you create
a standalone documentation project you remove the main "pro" for this
solution.

> 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
>
>

---------------------------------------------------------------------
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