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.
<snip>
Open source documentation is driven by the needs of the developer, not the utility towards the customer. The need avalon has wrt documentation atm isThoughts?
- 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 maintaining.
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.
cheers,
- Leo
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
