geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hernan Cunico <>
Subject Re: Geronimo Web site structure update
Date Wed, 03 May 2006 13:26:59 GMT
Most of the documentation was uploaded into a JIRA and granted ASF license long time ago. I
say most 
because the last updates have not been yet uploaded. Once we have in production
license should no longer be an issue.


Matt Hogstrom wrote:
> Hernan Cunico wrote:
>> I'll try to keep it short but can't help it, I like to write :)
>> Aaron Mulder wrote:
>>> While I grant that the proposed documentation page is sleeker in
>>> appearance than the current library page, I prefer not to emphasize
>>> any one source of documentation over the others.  I am not
>>> recommending that we make the documentation into the table of contents
>>> for my book, nor that we turn it into the index of DeveloperWorks
>>> articles pertinent to Geronimo, nor that we simply make it a list of
>>> Geronimo books available at Amazon or Safari.  Yet all of these are
>>> probably valuable to people looking to get started with Geronimo.
>> Where I am going with this idea is to try to get the things more clear 
>> around the web site and get more people participating in the 
>> documentation. I am not claiming as mine the documentation that is in 
>> Confluence, it is the Apache Geronimo's documentation and we ship an 
>> HTML version with Geronimo.
>>> Hernan, I don't intend to be rude, but this is the second time you've
>>> proposed this.  Can you find a way to construct a nice-looking
>>> documentation page that equally features all the sources of Geronimo
>>> documentation, instead of turning it into a list of articles you've
>>> contributed?  I'll be happy to work with you on this if you need help
>>> populating topics or highlights or blurbs for the documentation other
>>> than your own.
>> I would like to emphasize that I am not proposing to remove any of the 
>> current content but rather to add more content.  I think it would be 
>> more organized to have online books, printed books, interviews, etc. 
>> listed under "Library" and the documentation listed under 
>> "Documentation".
> If my understanding is correct you are suggesting that articles and 
> documentation where the copyright is owned by someone else be put in the 
> library and content that is ASF copyrighted be in the documentation 
> section.  I think the distinction makes sense.  So in your example 
> Hernan all the documentation you've provided is owned by the Geronimo 
> project and you have granted the copyright to the ASF? I think the 
> distinction makes sense.  I very much would like to see a comprehensive 
> set of doc owned by the project as that would really improve a user's 
> experience.  So long as we provide a prominent place for other people's 
> significant work as well I like this idea.
>> This is the Geronimo documentation. I have been nearly "begging" in 
>> the mailing lists for more people to contribute to the documentation 
>> and several people have already contributed.  I (I should say we all) 
>> could really use your help filling up some of the blanks in the 
>> current confluence based documentation.
>>> And on the subject of the Confluence documentation, perhaps we (the
>>> community, I know this is not entirely in Hernan's control) should
>>> consider revising the page headers.  Right now they tend to include
>>> something like:
>>> "Added by Tom Smith, last edited by Tom Smith ... (bold) Article
>>> donated by: Tom Smith"
>>> I don't think that's actually productive.  To be honest, I think it
>>> probably discourages contributions.  For example, if someone in the
>> All wikis behave alike in that aspect. If I create a new page my name 
>> will get stuck to that page as "Added by ..." but it will also reflect 
>> the last person who modified it as "last edited by ..." That is the 
>> way the wikis have for tracking changes.
>> Either way, I agree with you. I would prefer no names at all to be 
>> listed and the cool thing about the is that we can 
>> customize the HTML cached view so we will not have to deal with this 
>> issue anymore :)
>>> community writes some content and supplies it as a patch, the page
>>> will still say "Added by (some committer), last edited by (some
>>> committer)".  That's not entirely fair.  And if someone sees a typo in
>>> an article that says in bold at the top "Article donated by: Tom
>>> Smith", are they supposed to fix it?  If so, should it be "Article
>>> donated by: Tom Smith and John Doe" or "Article donated by: Tom Smith
>>> with updates from John Doe" or just leave it as "Article donated by:
>>> Tom Smith" but "last edited by John Doe" or what?  Even if we had a
>>> policy I think it would be a mental barrier to actually updating the
>>> page.
>> Well, you do not need to be a committer to work on any article, you 
>> just need to register in Confluence (just like with any other wiki) 
>> and pour your content there. To mitigate the "de facto" [Added by...] 
>> / [last edited by...], the "Article donated by:..." line was manually 
>> incorporated to each article.  I thought it would actually encourage 
>> more people to contribute.  The whole point behind this idea is to 
>> have more people interested in contributing to the documentation.
>> I also believe that by initially creating a structure/placeholders it 
>> should be easier for anyone to pick a subject and start writing about 
>> it as well as providing new topics to cover.
>>> I think it would be better overall if the Wiki documentation pages had
>>> no credits at all, and we just let the editorial history live in the
>>> Info page, and we invite the community to be active in authoring and
>>> updating the Wiki pages.  Do others agree?  Can that be arranged?
>> I totally agree with you, we should all be more proactive encouraging 
>> the community to contribute to the documentation too.
>> I currently don't know how to remove the "WHOs" from confluence but 
>> I'm looking how to do it.
>> Thanks for the feedback, I know you guys are very busy closing JIRAS.
>> Cheers!
>> Hernan
>>> Thanks,
>>>   Aaron
>>> On 5/2/06, Hernan Cunico <> wrote:
>>>> Hi All,
>>>> when we updated the web site we mainly focused on the look & feel 
>>>> but left the existing navigational
>>>> structure pretty much untouched.
>>>> I propose we update some of the structure starting with the 
>>>> documentation section. Currently there
>>>> are two links pointing to the same resource, these are 
>>>> *Documentation* and *Library*. Today we have
>>>> an official documentation for v1.0 and we are working on the doc for 
>>>> v1.1, in addition there is the
>>>> "Developers Guide" also being developed.
>>>> All these are the documentation that should be pointed from the 
>>>> "Documentation" link. What is
>>>> currently pointed from both "Documentation" and "Library" links 
>>>> should be just pointed from
>>>> "Library". We will also need to update the Geronimo Administration 
>>>> Console to reflect this changes
>>>> as the documentation is pointed as the "Additional documentation" link.
>>>> The documentation today is hosted on an external site (Atlassian) 
>>>> but we are working with the ASF
>>>> infrastructure team to get a local high performance installation 
>>>> ( Until we
>>>> resolve the ASF local installation I think we could point directly 
>>>> to the remote articles from our
>>>> site. This might be easier to explain by an example so I put 
>>>> together a copy of the Geronimo web
>>>> site with the proposed changes, see "Library" and "Documentation" 
>>>> links (note that the rest of the
>>>> site may not be entirely up-to-date)
>>>> Here is the test URL:
>>>> I think these proposed changes will facilitate access to the 
>>>> documentation, increase it's visibility
>>>> and hopefully we will see more volunteers to continue developing the 
>>>> docs.
>>>> Thoughts, comments, suggestions!?
>>>> Cheers!
>>>> Hernan

View raw message