request for documentation enhancement

[Leo Simons <le...@apache.org>]

I would like to ask that package maintainers (or where they checked
stuff in but didn't maintain it, those people) make sure that packages
they submit contain some minimal documentation.

*yet another rant requesting more docs below*

Here's some pointers wrt 'bare minimum':

- a README.txt inside the package root directory containing a
one-paragraph summary of the package, including intended usage, rough
package stability (ie pre-alpha, alpha, beta, stable) and relationship
to other packages where applicable

- a src/xdocs/index.xml file containing at least the same summary

- a simple example of basic use of the package of some kind (getting
started docs, source code example, etc)

- API documentation, at a minimum a package.html file in the package
root

Where you find it too cumbersome to write/maintain this level of
documentation, please include a README.txt stating the package is
pre-alpha and not fit for use.

There's *a lot* of subsubsubsubprojects atm, and I'm sure that when it
gets confusing for committers it is a hell for (potential) users. While
I'm okay with lots of subsubsubsubprojects, I feel that they are 90%
worthless to the community if it is not clear at a glance what they do.

I've said it before (like Paul has), but I think I'll keep saying it
till things are fixed...

thanks,

Leo



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: request for documentation enhancement

[Leo Simons <le...@apache.org>]

On Fri, 2002-09-20 at 18:06, Peter Donald wrote:
> Thanks for volunteering. If you would start with the stable packages that 
> would be great.

was expecting that one =)

I would have finished it all by now if I had the time. However things
are being added quicker than I can write xdoc, and they're being added
with zero docs.

cheers,

LSD




--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: request for documentation enhancement

[Peter Donald <pe...@apache.org>]

Thanks for volunteering. If you would start with the stable packages that 
would be great.

On Sat, 21 Sep 2002 01:37, Leo Simons wrote:
> I would like to ask that package maintainers (or where they checked
> stuff in but didn't maintain it, those people) make sure that packages
> they submit contain some minimal documentation.
>
> *yet another rant requesting more docs below*
>
> Here's some pointers wrt 'bare minimum':
>
> - a README.txt inside the package root directory containing a
> one-paragraph summary of the package, including intended usage, rough
> package stability (ie pre-alpha, alpha, beta, stable) and relationship
> to other packages where applicable
>
> - a src/xdocs/index.xml file containing at least the same summary
>
> - a simple example of basic use of the package of some kind (getting
> started docs, source code example, etc)
>
> - API documentation, at a minimum a package.html file in the package
> root
>
> Where you find it too cumbersome to write/maintain this level of
> documentation, please include a README.txt stating the package is
> pre-alpha and not fit for use.
>
> There's *a lot* of subsubsubsubprojects atm, and I'm sure that when it
> gets confusing for committers it is a hell for (potential) users. While
> I'm okay with lots of subsubsubsubprojects, I feel that they are 90%
> worthless to the community if it is not clear at a glance what they do.
>
> I've said it before (like Paul has), but I think I'll keep saying it
> till things are fixed...
>
> thanks,
>
> Leo

-- 
Cheers,

Peter Donald
----------------------------------------
"Liberty means responsibility. That is 
      why most men dread it." - Locke
---------------------------------------- 



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>