You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geronimo.apache.org by Hernan Cunico <hc...@gmail.com> on 2006/05/02 21:27:06 UTC
Geronimo Web site structure update
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
Re: Geronimo Web site structure update
Posted by Hernan Cunico <hc...@gmail.com>.
Done,
You'll see the change in the next update.
Cheers!
Hernan
Jason Dillon wrote:
> Can we use this URL for JIRA:
>
> http://issues.apache.org/jira/browse/GERONIMO
>
> instead of the version that is up there now:
>
> http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10220
>
> --jason
>
>
> On 5/2/06, Hernan Cunico <hc...@gmail.com> 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
>>
>
Re: Geronimo Web site structure update
Posted by Jason Dillon <ja...@planet57.com>.
Can we use this URL for JIRA:
http://issues.apache.org/jira/browse/GERONIMO
instead of the version that is up there now:
http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10220
--jason
On 5/2/06, Hernan Cunico <hc...@gmail.com> 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
>
Re: Geronimo Web site structure update
Posted by Aaron Mulder <am...@alumni.princeton.edu>.
On 5/3/06, Hernan Cunico <hc...@gmail.com> wrote:
> I will go ahead an implement this changes (including the proposal for the documentation), will need
> the XBean and GBuild info from you before though :)
It's great to see more participation in the documentation. However,
please revise the proposal as I've asked before applying it.
Thanks,
Aaron
> David Blevins wrote:
> >
> > On May 2, 2006, at 12:27 PM, Hernan Cunico wrote:
> >
> >>
> >> 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!?
> >>
> >
> > One request. Can the Subprojects tab lead to a subprojects.html page
> > that lists XBean and GBuild as well as DevTools? The DevTools section
> > of the page could link to devtools.html. I'd be happy to add at least
> > some minimal info to the xbean.html and gbuild.html pages.
> >
> > Thoughts?
> >
> >
>
Re: Geronimo Web site structure update
Posted by David Blevins <da...@visi.com>.
On May 3, 2006, at 2:55 PM, Hernan Cunico wrote:
> Great, if you can provide with some content for XBean and GBuild I
> will create the respective directories and reorg accordingly.
>
> devtools.html is currently at root level so I will move it to the
> existing devtools directory and rename it as index.html.
>
> I will go ahead an implement this changes (including the proposal
> for the documentation), will need the XBean and GBuild info from
> you before though :)
>
For GBuild if you can add content from these three pages that'd be
good enough for now:
index.html -- http://opensource.atlassian.com/confluence/oss/display/
GBuild/Home
overview.html -- http://opensource.atlassian.com/confluence/oss/
display/GBuild/GBuild+Agent+Overview
hosts.html -- http://opensource.atlassian.com/confluence/oss/display/
GBuild/Hosts
For XBean this would be good enough to get kicked off:
index.html -- http://docs.codehaus.org/display/XB/Home
custom-xml.html -- http://docs.codehaus.org/display/XB/Custom+XML
editing-xml.html -- http://docs.codehaus.org/display/XB/Editing+Custom
+XML
ant-task.html -- http://docs.codehaus.org/display/XB/http://
www.xbean.org/XBean+Ant+Task
Hey Guillaume, you willing to help out with content for the XBean
side of things? Maybe add a download page and some info on the 2.3
release as soon as it's out.
-David
Re: Geronimo Web site structure update
Posted by Hernan Cunico <hc...@gmail.com>.
Great, if you can provide with some content for XBean and GBuild I will create the respective
directories and reorg accordingly.
devtools.html is currently at root level so I will move it to the existing devtools directory and
rename it as index.html.
I will go ahead an implement this changes (including the proposal for the documentation), will need
the XBean and GBuild info from you before though :)
Cheers!
Hernan
David Blevins wrote:
>
> On May 2, 2006, at 12:27 PM, Hernan Cunico wrote:
>
>>
>> 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!?
>>
>
> One request. Can the Subprojects tab lead to a subprojects.html page
> that lists XBean and GBuild as well as DevTools? The DevTools section
> of the page could link to devtools.html. I'd be happy to add at least
> some minimal info to the xbean.html and gbuild.html pages.
>
> Thoughts?
>
>
Re: Geronimo Web site structure update
Posted by Matt Hogstrom <ma...@hogstrom.org>.
+1
David Blevins wrote:
>
> On May 2, 2006, at 12:27 PM, Hernan Cunico wrote:
>
>>
>> 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!?
>>
>
> One request. Can the Subprojects tab lead to a subprojects.html page
> that lists XBean and GBuild as well as DevTools? The DevTools section
> of the page could link to devtools.html. I'd be happy to add at least
> some minimal info to the xbean.html and gbuild.html pages.
>
> Thoughts?
>
>
>
>
Re: Geronimo Web site structure update
Posted by David Blevins <da...@visi.com>.
On May 2, 2006, at 12:27 PM, Hernan Cunico wrote:
>
> 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!?
>
One request. Can the Subprojects tab lead to a subprojects.html page
that lists XBean and GBuild as well as DevTools? The DevTools
section of the page could link to devtools.html. I'd be happy to add
at least some minimal info to the xbean.html and gbuild.html pages.
Thoughts?
Re: Geronimo Web site structure update
Posted by Dain Sundstrom <da...@iq80.com>.
On May 2, 2006, at 5:15 PM, Hernan Cunico wrote:
> 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".
It's all documentation to me and I think it should all be listed
together.
-dain
Re: Geronimo Web site structure update
Posted by Matt Hogstrom <ma...@hogstrom.org>.
No, I wasn't suggesting that updating the Wiki hoses up the copyright. You have a much better
understanding of copyrights and ownership than I do; you've written a book and I can barely read.
What I was referring to was my perceived distinction between project documentation and supporting
documentation. I saw project documentation of the sort that many other projects have where they
document their project and you get access to the documentation on the ASF infrastructure. The
library documentation I saw as a collection of pointers to documentation that was housed elsewhere
and not "owned" by the project.
It wasn't my intent to make any finer distinction than that.
Aaron Mulder wrote:
> On 5/3/06, Hernan Cunico <hc...@gmail.com> wrote:
>> 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
>> cwiki.apache.org in production the
>> license should no longer be an issue.
>
> Are you saying that people can't just edit the Wiki without hosing up
> the documentation license? I guess there's not anywhere in the Wiki
> edit process that prompts you to grant copyright to the ASF. Does
> this mean we need Jira issues submitted with all documentation changes
> so that we can get the license check ticked?
>
> Thanks,
> Aaron
>
>> 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 <hc...@gmail.com> 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
>> >>>>
>> >>>
>> >>
>> >>
>> >>
>> >
>>
>
>
>
Re: Geronimo Web site structure update
Posted by Geir Magnusson Jr <ge...@pobox.com>.
Aaron Mulder wrote:
> On 5/3/06, Hernan Cunico <hc...@gmail.com> wrote:
>> 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
>> cwiki.apache.org in production the
>> license should no longer be an issue.
>
> Are you saying that people can't just edit the Wiki without hosing up
> the documentation license? I guess there's not anywhere in the Wiki
> edit process that prompts you to grant copyright to the ASF.
Copyright is never granted to the ASF. The ASF only asserts a
"collective copyright" on the pile of things in a distribution (of
whatever sort) that in fact have copyright distributed throughout the
set of contributors.
> Does
> this mean we need Jira issues submitted with all documentation changes
> so that we can get the license check ticked?
Well, that would be one way if we had a doco system like that. :)
But since we're using the wiki, I think the simplest thing is to have a
clear "terms of contribution" somewhere on the wiki, and maybe a link to
it at the bottom of each page.
Here is some suggested wording :
"This wiki has been created for public contribution of material about
projects of The Apache Software Foundation (the "Foundation"), a
Delaware nonprofit corporation classified as a public charity under
501(c)(3). All contributions intentionally submitted to the Foundation
on this wiki is considered a Contribution to the Foundation unless
otherwise noted in the contribution. The terms and conditions that apply
to your Contributions are defined by either a contributor license
agreement (CLA) signed by you and/or your employer or, if no such CLA is
on file at the Foundation, by the terms and conditions of Contributions
as defined by the Apache License, Version 2.0."
My 0.02
geir
>
> Thanks,
> Aaron
>
>> 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 <hc...@gmail.com> 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
>> >>>>
>> >>>
>> >>
>> >>
>> >>
>> >
>>
>
>
Re: Geronimo Web site structure update
Posted by Aaron Mulder <am...@alumni.princeton.edu>.
On 5/3/06, Hernan Cunico <hc...@gmail.com> wrote:
> 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 cwiki.apache.org in production the
> license should no longer be an issue.
Are you saying that people can't just edit the Wiki without hosing up
the documentation license? I guess there's not anywhere in the Wiki
edit process that prompts you to grant copyright to the ASF. Does
this mean we need Jira issues submitted with all documentation changes
so that we can get the license check ticked?
Thanks,
Aaron
> 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 <hc...@gmail.com> 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
> >>>>
> >>>
> >>
> >>
> >>
> >
>
Re: Geronimo Web site structure update
Posted by Hernan Cunico <hc...@gmail.com>.
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 cwiki.apache.org in production the
license should no longer be an issue.
Cheers!
Hernan
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 <hc...@gmail.com> 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
>>>>
>>>
>>
>>
>>
>
Re: Geronimo Web site structure update
Posted by Matt Hogstrom <ma...@hogstrom.org>.
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 <hc...@gmail.com> 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
>>>
>>
>
>
>
Re: Geronimo Web site structure update
Posted by Hernan Cunico <hc...@gmail.com>.
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".
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 <hc...@gmail.com> 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
>>
>
Re: Geronimo Web site structure update
Posted by Aaron Mulder <am...@alumni.princeton.edu>.
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.
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.
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
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.
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?
Thanks,
Aaron
On 5/2/06, Hernan Cunico <hc...@gmail.com> 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
>