avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <leosim...@apache.org>
Subject Re: http://avalon.apache.org/
Date Tue, 28 Jan 2003 10:22:53 GMT
Stephen McConnell wrote:
> Thanks a million for getting this done.
> I would like to get some feedback and opinions about the Avalon webpages 
> bacause I think now is the time to handle any restructing of approach, 
> message, and so on.  I think the historical project oriented approach 
> has left a lot of users confussed and has negivively impacted the take 
> up on Avalon.  I would like to suggest we rethink the the subjects we 
> are trying to comminicate and get down to some good old-fasshioned human 
> engineering on our web site.
> I see two distinct "views" of Avalon - a "products view" and a 
> "functional view":
> If I compare this with the old and current Avalon site I see total 
> domination of of the Project/CVS view - Framework, Excalibur, 
> Cornerstone, Phoneix, Apps, Logkit (horizontally and vertically). 
> Content presention should not been driven by the CVS structure - instead 
> content and structure should be addressing utility for the customer.
> Thoughts?

Open source documentation is driven by the needs of the developer, not 
the utility towards the customer. The need avalon has wrt documentation 
atm is

- making lots of things explicit (like the term "appliance") so we are 
no longer confused ourselves
- writing user documentation for our products. Ie, if you use a product, 
how do you do so? Which features does it have, and how do you use those? 
Where is the product heading?
- documentation on how our community and development process works (and 
I'll be hopefully just referring to incubator docs when I get access 
there :D)

You cannot get at functional view until you have a reasonably complete 
product view. And the functional view is a bitch to maintain simply 
because no-one ever feels like maintaining it (just look at OSS history: 
it doesn't work). Even the "guidebook/tutorial" view (which is the third 
one), ie "Developing with Avalon", is something no-one really feels like 

So sure, it would be real good to have a 'functional view'. I just don't 
see us maintain it (for an example of how bad we are at even maintaining 
the product view, see 
http://jakarta.apache.org/avalon/framework/reference-containers.html. It 
still links to a broken page on the OSM site, and has been doing so for 
a long time now). What you get then is a broken functional view, which 
is worse than none, especially when coupled with a broken product view.

If you are more confident than me, please do go set it up :D But I'd 
rather have you invest that energy in product/guidebook view first until 
that documentation is reasonably correct and up-to-date.


- Leo

To unsubscribe, e-mail:   <mailto:avalon-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-dev-help@jakarta.apache.org>

View raw message