> > >Other than that, Excalibur really needs > > >documentation badly. > > > > Would it be better that instead of describing each component > individually > > we point them to package.html for each package??? We could then > just have a > > short highlevel description in xdocs which points to package.html for > > further data??? > > I would like to see implementation details in the package.html files--but > have the package.html files generated by XSLT. (In other words we use our > document DTD to write those docs).
That's what I've been thinking about. I wonder, is it possible with the current setup to not have "dtd" dirs all across your xdocs project (seems like a bad design choice, and all but impossible to use when you want to do doc generation inside the java source tree). > The high-level description should be more "what is it" and "what > does it do", > while the package.html describes "how do I use it". Why? Looking at the java setup, it seems to be more the reverse: the API is academic in tone, while the tutorial series document how to use the API. I think I like that one better: good programmers are interested in high-level overviews and have no prob reading api docs; new programmers need a tutorial and more down-to-earth docs. cheers, LSD, who is working on a "Getting Started with the Avalon Framework" tutorial. PS: anyone know a good paper about COP to refer to? --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
