geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hernan Cunico <hcun...@gmail.com>
Subject Re: Geronimo Web site structure update
Date Wed, 03 May 2006 00:15:16 GMT
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 <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