geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Matt Hogstrom <m...@hogstrom.org>
Subject Re: Geronimo Web site structure update
Date Wed, 03 May 2006 19:35:21 GMT
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 <hcunico@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 <hcunico@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
>> >>>>
>> >>>
>> >>
>> >>
>> >>
>> >
>>
> 
> 
> 

Mime
View raw message