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: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
