RE: New Committer

[Huw Roberts <Hu...@mmlive.com>]

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

> - Paul


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.

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?

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

Re: New Committer

[Paul Hammant <Pa...@yahoo.com>]

Huw,

>>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. 
>
Kinda.

>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?
>
Nope.

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:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>