You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by Felix Knecht <fe...@otego.com> on 2011/03/04 10:11:19 UTC
[DISCUSS] Documentation as own project
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?
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?
Regards
Felix
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: [DISCUSS] Documentation as own project
Posted by Eric Charles <er...@apache.org>.
Yes, I already had issue with the intermediate step for site project :)
From what I understand, the publication should be based on svnpubsub,
so we still have to do the html generation.
http://www.apache.org/dev/cms.html#svnpubsub
To use the cms, james project must be enrolled in
https://cms.apache.org/ and a javascript bookmarklet should be used.
Tks,
- Eric
On 4/03/2011 17:14, Stefano Bagnara wrote:
> 2011/3/4 Eric Charles<er...@apache.org>:
>> Hi,
>> I forgot the archive section.
>> We could simply keep in svn "site" project the generated html and remove the
>> src xdocs.
> No, please. svn generated site is not considered a source ATM. In past
> we often debated its usage at all. We just kept it as a disaster
> recovery "helper" and since ASF introduced backup and full disaster
> recovery for www content we also said we could have removed it at all
> from our SVN as there was no reason to keep this extra step around.
> (Every minor change to the template creates really big svn diffs and
> it is simply a waste of time and svn space, IMHO).
>
> IMO either we keep the xdocs for the 2.2 docs or we decide no one is
> interested in 2.2 anymore and remove them from both the src and the
> generated site.
>
>> About next CMS for james, I read
>> http://www.apache.org/dev/cms.html#confluence-phaseout.
> Ouch.. I wasn't aware of this stuff? ASF sends messages to
> people@apache.org for trivial things, why didn't they wrote anything
> about such a major change? (Or maybe they did and I missed it?)
> I summarize: "mantaining the confluence export plugin is a big effort"
> so "we write our own CMS"... A bit weird. BTW I'm sure this has been
> discussed by people having power to decide, so let's just take it as a
> fact.
>
> Does this ASF CMS have an online editor or people is forced to deal
> with SVN to use it? Is there a place to test it?
>
>> There's also considerations on formats
>> http://www.apache.org/dev/cms.html#markdown
>>
>> We could extend this discussion to the way we are going to formalize/publish
>> documentation in the future. This could give use some tips on how to
>> structure the projects/modules.
> Sure, but I'm now a bit confused by the cms page you pointed me to, so
> I have to take a while to digest it.
>
> 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
Re: [DISCUSS] Documentation as own project
Posted by Stefano Bagnara <ap...@bago.org>.
2011/3/4 Eric Charles <er...@apache.org>:
> Hi,
> I forgot the archive section.
> We could simply keep in svn "site" project the generated html and remove the
> src xdocs.
No, please. svn generated site is not considered a source ATM. In past
we often debated its usage at all. We just kept it as a disaster
recovery "helper" and since ASF introduced backup and full disaster
recovery for www content we also said we could have removed it at all
from our SVN as there was no reason to keep this extra step around.
(Every minor change to the template creates really big svn diffs and
it is simply a waste of time and svn space, IMHO).
IMO either we keep the xdocs for the 2.2 docs or we decide no one is
interested in 2.2 anymore and remove them from both the src and the
generated site.
> About next CMS for james, I read
> http://www.apache.org/dev/cms.html#confluence-phaseout.
Ouch.. I wasn't aware of this stuff? ASF sends messages to
people@apache.org for trivial things, why didn't they wrote anything
about such a major change? (Or maybe they did and I missed it?)
I summarize: "mantaining the confluence export plugin is a big effort"
so "we write our own CMS"... A bit weird. BTW I'm sure this has been
discussed by people having power to decide, so let's just take it as a
fact.
Does this ASF CMS have an online editor or people is forced to deal
with SVN to use it? Is there a place to test it?
> There's also considerations on formats
> http://www.apache.org/dev/cms.html#markdown
>
> We could extend this discussion to the way we are going to formalize/publish
> documentation in the future. This could give use some tips on how to
> structure the projects/modules.
Sure, but I'm now a bit confused by the cms page you pointed me to, so
I have to take a while to digest it.
Stefano
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: [DISCUSS] Documentation as own project
Posted by Eric Charles <er...@apache.org>.
Hi,
I forgot the archive section.
We could simply keep in svn "site" project the generated html and remove
the src xdocs.
About next CMS for james, I read
http://www.apache.org/dev/cms.html#confluence-phaseout.
There's also considerations on formats
http://www.apache.org/dev/cms.html#markdown
We could extend this discussion to the way we are going to
formalize/publish documentation in the future. This could give use some
tips on how to structure the projects/modules.
Tks,
- Eric
On 4/03/2011 15:07, Stefano Bagnara wrote:
> 2011/3/4 Eric Charles<er...@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<fe...@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
>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: [DISCUSS] Documentation as own project
Posted by Stefano Bagnara <ap...@bago.org>.
2011/3/4 Eric Charles <er...@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<fe...@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
Re: [DISCUSS] Documentation as own project
Posted by Felix Knecht <fe...@apache.org>.
The discussion will be ongoing for quite a time (I think) until we'll
come to a decision. To generate the reports and the already existing
xdocs sites side by side I'll create a profile 'site-reports' which
generates the technical reports. Just running mvn site without profile
will generate the site without reports as it does already now.
On 03/05/2011 06:45 AM, Eric Charles wrote:
> On 4/03/2011 15:27, Felix Knecht wrote:
>> No matter which CMS (or maven) we use for documentation, IMO it makes
>> it easier to generate those technical maven reports when they can be
>> generated on there own without having included any documentation.
>>
>
> True.
>
> What about:
> - Leave reports and code related doc in the modules (and publish them
> under http://james.apache.org/dev) - mvn xdoc based
> - Start a simple documentation project which will be the home page
> (http://james.apache.org) and smoothly migrate what can be migrated
> there - new CMS markdown format.
>
> Tks,
> - Eric
>
>> ---------------------------------------------------------------------
>> 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
Re: [DISCUSS] Documentation as own project
Posted by Eric Charles <er...@apache.org>.
On 4/03/2011 15:27, Felix Knecht wrote:
> No matter which CMS (or maven) we use for documentation, IMO it makes
> it easier to generate those technical maven reports when they can be
> generated on there own without having included any documentation.
>
True.
What about:
- Leave reports and code related doc in the modules (and publish them
under http://james.apache.org/dev) - mvn xdoc based
- Start a simple documentation project which will be the home page
(http://james.apache.org) and smoothly migrate what can be migrated
there - new CMS markdown format.
Tks,
- Eric
> ---------------------------------------------------------------------
> 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
Re: [DISCUSS] Documentation as own project
Posted by Felix Knecht <fe...@apache.org>.
On 03/04/2011 02:45 PM, Eric Charles wrote:
> 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.
No matter which CMS (or maven) we use for documentation, IMO it makes it
easier to generate those technical maven reports when they can be
generated on there own without having included any documentation.
Felix
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: [DISCUSS] Documentation as own project
Posted by Eric Charles <er...@apache.org>.
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<fe...@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
Re: [DISCUSS] Documentation as own project
Posted by Stefano Bagnara <ap...@bago.org>.
2011/3/4 Felix Knecht <fe...@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
Re: [DISCUSS] Documentation as own project
Posted by Stefano Bagnara <ap...@bago.org>.
2011/3/5 Eric Charles <er...@apache.org>:
> Interesting numbers.
> I don't have enough background to get facts from these numbers.
> Did you feel/see any evolution about the page/site frequentations ?
Traffic has been stable in the last 5 years.
> About download, james 3 numbers are probably a bit higher cause we often
> redirect to the maven snapshots downloads :)
True. Also they are different stuff. People downloading 2.3 will
download only once. Instead people downloading the 3.0 are going to
download each new release at least until we release a final.
> For my info, do these numbers come from google analytics?
Yes
> On 4/03/2011 14:39, Stefano Bagnara wrote:
>>
>> 2011/3/4 Eric Charles<er...@apache.org>:
>>>
>>> Hi Felix,
>>>
>>> The "server" docs in project "project" is some left-over. It should be
>>> cleaned (migrated to server 2.x, or simply deleted).
>>> I was glad to see the reports you generated cause it really bring value,
>>> but
>>> also found the resulting menus too heavy: james project/modules has
>>> already
>>> numerous and putting extra info on the website is only readable/usable by
>>> a
>>> daily-committer.
>>>
>>> I find that your proposal to have a separated documentation project,
>>> leaving
>>> the technical reports at their place (in each project/module) really
>>> makes
>>> sense.
>>>
>>> I would also like to discuss the types of documentation:
>>> - End user willing to use (=configure, operate,..) the "james server" as
>>> a
>>> package.
>>> - End user willing to use a specific library from the outside (for
>>> example
>>> mailbox).
>>> - Developer willing to go into the librairies (the internals).
>>>
>>> At that occasion, I would also like to talk about the url and the way
>>> james
>>> is presented.
>>>
>>> Maybe I'm wrong, but most of the visitors simply except a download button
>>> for "james server" in a pack, but a small startup guide.
>>> This should be the james home page.
>>>
>>> The others could have links to browser other websites hosted on other
>>> james
>>> urls.
>>
>> Here are some stats from the last year:
>> 720K page viewed
>> ---------------------
>> 236K "server"
>> 180K homepage
>> 120K "downloads"
>> 39K "mailet"
>> 32K "mime4j"
>> 28K "hupa"
>> 11K "jspf"
>> 10K "imap"
>> ......
>>
>> And about real downloads (only from the download pages, as we also
>> have some stuff in maven and is not tracked here):
>> ------
>> 29K server downloads
>> 6K mime4j downloads
>> 1.4K mailets
>> 1K jspf
>> .....
>>
>>
>> Of the 29K server downloads, 26K are 2.3.x and 3K are 3.0 milestones.
>>
>> Even in the last months 3/4 of downloads are still about v2.3
>>
>> 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
Re: [DISCUSS] Documentation as own project
Posted by Eric Charles <er...@apache.org>.
Interesting numbers.
I don't have enough background to get facts from these numbers.
Did you feel/see any evolution about the page/site frequentations ?
About download, james 3 numbers are probably a bit higher cause we often
redirect to the maven snapshots downloads :)
For my info, do these numbers come from google analytics?
Tks,
- Eric
On 4/03/2011 14:39, Stefano Bagnara wrote:
> 2011/3/4 Eric Charles<er...@apache.org>:
>> Hi Felix,
>>
>> The "server" docs in project "project" is some left-over. It should be
>> cleaned (migrated to server 2.x, or simply deleted).
>> I was glad to see the reports you generated cause it really bring value, but
>> also found the resulting menus too heavy: james project/modules has already
>> numerous and putting extra info on the website is only readable/usable by a
>> daily-committer.
>>
>> I find that your proposal to have a separated documentation project, leaving
>> the technical reports at their place (in each project/module) really makes
>> sense.
>>
>> I would also like to discuss the types of documentation:
>> - End user willing to use (=configure, operate,..) the "james server" as a
>> package.
>> - End user willing to use a specific library from the outside (for example
>> mailbox).
>> - Developer willing to go into the librairies (the internals).
>>
>> At that occasion, I would also like to talk about the url and the way james
>> is presented.
>>
>> Maybe I'm wrong, but most of the visitors simply except a download button
>> for "james server" in a pack, but a small startup guide.
>> This should be the james home page.
>>
>> The others could have links to browser other websites hosted on other james
>> urls.
> Here are some stats from the last year:
> 720K page viewed
> ---------------------
> 236K "server"
> 180K homepage
> 120K "downloads"
> 39K "mailet"
> 32K "mime4j"
> 28K "hupa"
> 11K "jspf"
> 10K "imap"
> ......
>
> And about real downloads (only from the download pages, as we also
> have some stuff in maven and is not tracked here):
> ------
> 29K server downloads
> 6K mime4j downloads
> 1.4K mailets
> 1K jspf
> .....
>
>
> Of the 29K server downloads, 26K are 2.3.x and 3K are 3.0 milestones.
>
> Even in the last months 3/4 of downloads are still about v2.3
>
> 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
Re: [DISCUSS] Documentation as own project
Posted by Stefano Bagnara <ap...@bago.org>.
2011/3/4 Eric Charles <er...@apache.org>:
> Hi Felix,
>
> The "server" docs in project "project" is some left-over. It should be
> cleaned (migrated to server 2.x, or simply deleted).
> I was glad to see the reports you generated cause it really bring value, but
> also found the resulting menus too heavy: james project/modules has already
> numerous and putting extra info on the website is only readable/usable by a
> daily-committer.
>
> I find that your proposal to have a separated documentation project, leaving
> the technical reports at their place (in each project/module) really makes
> sense.
>
> I would also like to discuss the types of documentation:
> - End user willing to use (=configure, operate,..) the "james server" as a
> package.
> - End user willing to use a specific library from the outside (for example
> mailbox).
> - Developer willing to go into the librairies (the internals).
>
> At that occasion, I would also like to talk about the url and the way james
> is presented.
>
> Maybe I'm wrong, but most of the visitors simply except a download button
> for "james server" in a pack, but a small startup guide.
> This should be the james home page.
>
> The others could have links to browser other websites hosted on other james
> urls.
Here are some stats from the last year:
720K page viewed
---------------------
236K "server"
180K homepage
120K "downloads"
39K "mailet"
32K "mime4j"
28K "hupa"
11K "jspf"
10K "imap"
......
And about real downloads (only from the download pages, as we also
have some stuff in maven and is not tracked here):
------
29K server downloads
6K mime4j downloads
1.4K mailets
1K jspf
.....
Of the 29K server downloads, 26K are 2.3.x and 3K are 3.0 milestones.
Even in the last months 3/4 of downloads are still about v2.3
Stefano
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org
Re: [DISCUSS] Documentation as own project
Posted by Eric Charles <er...@apache.org>.
Hi Felix,
The "server" docs in project "project" is some left-over. It should be
cleaned (migrated to server 2.x, or simply deleted).
I was glad to see the reports you generated cause it really bring value,
but also found the resulting menus too heavy: james project/modules has
already numerous and putting extra info on the website is only
readable/usable by a daily-committer.
I find that your proposal to have a separated documentation project,
leaving the technical reports at their place (in each project/module)
really makes sense.
I would also like to discuss the types of documentation:
- End user willing to use (=configure, operate,..) the "james server" as
a package.
- End user willing to use a specific library from the outside (for
example mailbox).
- Developer willing to go into the librairies (the internals).
At that occasion, I would also like to talk about the url and the way
james is presented.
Maybe I'm wrong, but most of the visitors simply except a download
button for "james server" in a pack, but a small startup guide.
This should be the james home page.
The others could have links to browser other websites hosted on other
james urls.
Tks,
- Eric
On 4/03/2011 10:11, Felix Knecht wrote:
> 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?
>
> 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?
>
> Regards
> Felix
>
> ---------------------------------------------------------------------
> 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