geronimo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Aaron Mulder" <ammul...@alumni.princeton.edu>
Subject Re: Geronimo Web site structure update
Date Tue, 02 May 2006 20:06:54 GMT
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 <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