avalon-phoenix-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Hammant <Paul_Hamm...@yahoo.com>
Subject Re: New Committer
Date Thu, 01 Aug 2002 06:35:13 GMT

>>I'd like to ask, hoping not to appear rude, what Huw thinks about xdocs 
>>and whether he'll consider their content as important as java source.
>i've been using Avalon stuff for two years, but i've only been making an
>effort to contribute for the last couple of months, so sorry if it takes me
>a little while to catch in.
No problem.

>not meaning to sound evasive, but i'm not sure what you mean exactly -
>do you mean:
>1) do i consider documentation as important as the .java, so i should get
>that done sooner, not later.  or that java shouldn't be submitted (or
>committed) without the accompanying documentation. 

>2) do i consider the xdoc markup to be as important as the java source in
>the sense that both are now used to create the management content?

I'm talking about src/xdocs/*  Most projects have this source, it gets 
transformed into HTML and it visible at http://jakarta.apache.org/avalon/...

I'm raising the issue because our documentation, particilarly website 
docs, are constantly critisized.  It does not matter how good our code 
is... (I could waffle for another 300 words).

Basically, only a subset of committers work on xdocs at all.  Some of 
them do content, some do infrastructure (stylesheets etc), some do both. 
 But the main point is that it is only a subset. We cannot bear the 
burdon on our own.  I expect I'm going to get flamed by others now. 
 This is not personal, it is just that I'd like to raise the bar for 
committer entry slightly <fx: ducks for more flames>.

- Paul

>as far as that goes, here's my POV.  xdoc is an optional, but convenient way
>to make the mxinfo files, especially since it can 'introspect' the class
>directly and fill in information automatically.  as it was already used to
>produce the xinfo files i didn't consider the implications of adopting it,
>since it does not impose any additional dependencies.  also, since its only
>needed to produce the mxinfo files, not by the SystemManager that reads
>them, our liability is limited to finding another way to produce the files
>in that format. (which is what i thought we'd do in order to
>internationalize the descriptions, if/when that's done).
>assuming this answer is somewhat on the mark, the next question is where do
>non-automatically generated mxinfo files fit in the source tree...

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

View raw message