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