Re: http://avalon.apache.org/

[Berin Loritsch]

Leo Simons wrote:

> 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>
>
>> 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


But our customers *are* developers. It's not hard to understand what we
need.

> - 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)


Right. All those things are needed.

> 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.


Something like that should not need to be altered that much. It is
meant to be a high level text. As the preferred container changes, it
should be updated to reflect that, but nothing more.


> 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.


Things like API docs, downloads, etc. are not going to change often.
Putting those at the top are important.



--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>