Response below:
Simon Kitching wrote:
Documentation is always last for developers :-). As it happens, however,
it is the area that *users* can productively contribute back to a
project.
Aside from documenting "things I found along the way", I disagree. First
of all, you have to have the information to produce documentation.
Acquiring this information requires the time of the developers -- there
is no reason for them to be dictating to someone, just write the
documentation. If the users knew the information already, the need for
documentation wouldn't be so dire. Second, relying on users for
documentation guarantees that documentation will always be an
after-the-fact effort. It should never be this way. Third, with the
already pointed-out pace of change, the documentation is virtually
guaranteed to always lag behind current feature and be inaccurate.
For a product released to the public, open source or not, documentation
should be there, accurate, and clear. The only reason for poor
documentation in any project is choice. Its just a reflection of the
level of excellence to which the project aspires -- and this is any
project, not just this one. The problem is that people have in this
equation in their head:
code == product.
This is inaccurate. The real equation is:
code + documentation + support == product
Look at it this way, and there would be less focus on bells and
whistles, and more focus on documentation and support of the product.
Brad
For a project like this (a small developer core but a very large user
base) a Wiki documentation site would seem tome to be an ideal fit. The
"User FAQ" facility where skilled users can post FAQ entries for newbies
is a step in that direction, but it is somewhat limited. And as a newbie
to maven2 myself, that FAQ is already intimidatingly large and
unstructured.
As it happens, there is a Maven wiki here:
http://docs.codehaus.org/display/MAVENUSER/Home
(The standard Apache wiki site http://wiki.apache.org/maven/
refers people to it).
There's a reasonable amount of content already, actually.
I would simply suggest putting a very prominent link to that wiki site
from the Maven homepage or documentation page - and maybe migrating all
the FAQ content onto the wiki.
The matter of adequate maven documentation then becomes the
responsibility of us, the users! From time to time wiki content may be
migrated into the core docs hosted on the maven site but there would be
no great urgency on that.
Cheers,
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
