Jason,
Thank you for setting up the mavenusers space on confluence. While this
solution is certainly better for integrating the documentation with
Maven, it has the disadvantage that it significantly raises the bar for
anyone who wants to contribute.
For example, unregistered users can't see its content, so they will not
be drawn to improve on the documentation in the confluence wiki. In
addition, anyone wishing to make a small contribution, will need to
register, then send you an email, wait for the confirmation -- which
will come quickly, I know, but will not be immediate. Most users will
not bother.
Let me give a few examples of possible user contributions that would not
make it into a registered-users-only wiki:
1. Someone asked in the mailing lists about which archetypes are
available by default with maven. Brett answered that by providing a
useful link to ibiblio.
I thought that this would be useful information for me, followed the
link and made a mental note to check back the mailing list when I need
this info sometimes in the future. When we started the discussion on the
wiki, I just went to the wiki, added three or four lines for the
archetypes I had found when following the link. Now I know, where to
find it.
2. I was looking through the guide to creating sites. There is a link
to a description ("A full reference of the APT Format is available").
The link is dead.
Of course I looked around a little more and found the full guide to the
apt format. Of course I didn't bother sending this information to the
mailing list. It looks like nit-picking but a wiki page would be ideal
to put this information.
3. Yesterday Wendy Smoak noted in the mailing list that the guide for
creating archetypes states that the <id> tag for the archetype.xml
should be the same as the <artifactId> but that this is not the case for
one of the plugins he used so the statement must be incorrect. It is
very unlikely that an observation like this will be caught if we don't
let the user who observes it contribute it easily.
I know that you have worked hard at the documentation for Maven. But
Maven is huge and complex. It is very difficult to put everything that
users need into writing. And it is probably difficult for any
experienced maven user - let alone developer - to understand how hard it
is to learn Maven.
In the past few weeks I have more than once regretted starting with
Maven. It is a great tool, but whatever I start with, I find that it is
so difficult to answer the basic questions that arise for the newbie.
And I know that I am not the only one. It should not be like that
(please don't take this as a criticism of the developers, I just think
that there must be better ways to involve all of us in augmenting the
documentation).
Would you see a big problem if we started a trial with the Wiki? There
is not much that we can loose. If nobody contributes or it really gets
defaced all the time, we just stop. We don't loose anything. On the
other hand, maybe we really get some users involved who submit snippets
of insights and we reduce the learning curve.
Would you really object if we wanted to launch a trial balloon for
linking Maven documentation with the wiki?
- Alexander
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
