avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Donald <pe...@apache.org>
Subject Re: Avalon Documentation Project
Date Thu, 18 Apr 2002 12:07:01 GMT
On Thu, 18 Apr 2002 06:09, Leo Simons wrote:
> I've been thinking about this for some time now, and I
> believe this all is sufficiently important to warrant an
> Avalon subproject (ie even people that don't use a single
> bit of avalon code could benefit tremendously from
> learning why it is so useful to program to interfaces,
> not have too many abstract classes, and separate that
> interface from its implementation, package-and-jar-wise).

We already have a CVS module set up for it - "jakarta-avalon-site" ;)

> I'd imagine having this subproject take care of
> everything that is currently on the website in more-
> or-less tutorial or guide form, that is, excluding
> the actual reference documentation, javadocs, and,
> when we get them the dependency and uml diagrams.
>
> Such an effort will fail if there is insufficient support
> from the programmers. A project needs a certain critical
> mass (number of commiters, FA), I guess, before this
> support can be delivered. Linux clearly has such critical
> mass (tldp.org is really useful). I am not sure we do; it
> depends on how much time each of us has to spend on docs.

I think it would definetly be useful and some of the documentation already 
fits into this category (namely a lot of Berins work). And given a resting 
place and good infrastructure it would be much easier to add more 
documentation. 

Several times I have gone to add documentation to phoenix and got frustrated 
with the issues re cocon and version compatability hell (ie xerces in phoenix 
is different to one in tools/**) and given up. 

The first step to getting more documentation done would be to make the whole 
process easier to do. I like the POI look and definetly that would be a good 
step forward. Combine that with an easy to add to set of documentation and I 
think we could do much better docs.

I like the idea of "recipes" which are essentially extended FAQs that describe 
how you go about doing something with avalon. They may also describe the 
context in which you would do it and the pros/cons of this approach.

As I have said before. If someone wants to set up the build process so it is 
easier I am more than willing to do documentation. But I just hate stuffing 
around with building the damn things ;)

-- 
Cheers,

Peter Donald


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


Mime
View raw message