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 cwiki.apache.org 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 <[EMAIL PROTECTED]> 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
>>>> (cwiki.apache.org). 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:
>>>>
>>>> http://people.apache.org/~hcunico/site/
>>>>
>>>> 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
>>>>
>>>
>>
>>
>>
>
