Leo, Having done a considerable amount of work on xdocs, I do not think we need to have a new project just for documentation. I think we need more people over coming an aversion to documentation. I myself have more to do I agee, but there are people here making code changes that are not making *any* changes to xdocs.
I agree that the need for documentation is great, but not quite as great as you claim : > and separate that interface from its implementation, package-and-jar-wise). http://jakarta.apache.org/avalon/framework/separation-of-interface-and-implementation.html That is one of our largest pages. It chief flaw, is that I (an English language cripple) wrote most of it. I'll reassert -> docs fixed by more joining in. - Paul >We have a little problem: most of the potential avalon >audience cannot quite grasp what avalon is about by >reading our docs. > >Avalon is not just about useful reusable components and >containers; using avalon promotes a style of programming. > >A large part of the added value avalon brings to a >programming project is similar to the added value of a >programming methodology (ie XP) or architectural >concept (ie design patterns). > >While it is very possible to use many bits of avalon >without adapting these ideas (ie take an excalibur >component jar to provide a DataSource impl with you >JDBC driver), the value of the DataSource is much >lower when you do so (there are other quality open >source DataSources with good documentation and >support). > >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). > >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. > >Lately, I'm getting the feeling that we have indeed now a >big enough developer team to make a move like this. >The amount of commits dealing with documentation is >growing in relationship to the amount of commits dealing >with code. > >Also, the parts of avalon that matter most with regards >to such a Documentation project are getting to a point >where they're stable enough: >- framework is not being revamped, but tweaked >- revamping of excalibur is mostly (from a documentation > viewpoint) irrelevant shifting of packages from location > to location >- cornerstone needs work but the use and code flow > patterns we have there are not changing that much >- phoenix needs cleanup but we've pretty much figured > out how it will look; as such, the external phoenix > api is stable enough to document >- applications is an entire beast on its own with some > very nice examples. >- logkit is solid as a rock and will only change when we > need to support the next big thing(tm) from MS or > somethin' ;) > >thoughts? > >- Leo > >--- >Avalon: the next big revolution in java programming. Now at >http://ourworld.compuserve.com/homepages/martinhighmore/ >--- > >-- >To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> >For additional commands, e-mail: <mailto:[EMAIL PROTECTED]> > > > -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
