avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <leosim...@apache.org>
Subject request for documentation enhancement
Date Fri, 20 Sep 2002 15:37:45 GMT
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

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



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

View raw message