Re: Next release?

[James CE Johnson]

Lester Ward wrote:

The thing I want to stress here is that if you think the docs are too poor but continue to use the program, then why not contribute yourself with some docs about the problems you just solved?

There is one problem with this mentality: if a newbie solves a problem, it
might be the most optimal "correct" way and it might not be. The newbie has
.no. way of knowing which of the two he's done. The people that have the
knowledge to make that judgment are the developers who, in this case, have
not yet shared this knowledge with documentation. This leaves the newbie
with only two choices: either get the full knowledge of the developer by
diving into the source code or shutting up. The best you can hope for in
this situation is that the newbie posts the solution he found to the mailing
list in some way that is easily found by a search.

In the past I've found it to be very useful for a newbie to create HOWTO and tutorial documents. I think this benefits the project and the user community in two ways:

1) The documentation is started. "know it all" developers can then go correct mistakes and enhance the docs. Either directly or though feedback to the author.

2) The newcomer will do what they think is the most correct, easiest, most obvious, whatever. By reading the newcomers impression of "correct" usage, the developers may find that they're not necessarily building things in the most obvious manner.

For example, I'm in the process of trying to get subprojects and the reactor
to work. I have something that works for me, but I'm pretty sure it is not
the "correct" way of doing things. Since I'm basically muddling along
without docs, I have no idea what the "correct" way really is.

Sometimes documenting the wrong way is just as important as documenting the right way. How many times have we read a book/document and wanted to ask the author "why did you do it *that* way when *this* way is easier?". If we could, the answer would frequently be "because the easy way leads you into trouble here, here and here..."

The solution to this is usually HOWTO documentation. The issue here is that
for someone like me, who is just trying to understand the system for the
first time, writing a HOWTO on, say, using Reactor will take days, as I plow
through the code, experiment with settings and so on. Someone who already
knows how it works (a developer) could write the same basic HOWTO in about
20 minutes.

Sure but is the developer-written document going to be as thorough? I mean, if they haven't had time to write it yet, what makes us think that they can kick out something detailed in 20 minutes? If a non-developer digs in deep they're likely to write a much more detailed document in the end.

When developers avoid creating even very basic documentation, what they are
really saying is "we don't care if you use our work or not". (Or, more
often, "we learned the product by plowing through the source, so you can
too".)

I think that is rarely the case. More often the developer is interested in solving the technical problems and reaching a stable milestone before commiting time and resources to documentation. I've been using maven since the Beta-4 days and if they had written complete documentation back then it would be largely irrelevant by now. Where's the point in that? Wait until things settle down...

That is a perfectly legitimate stance to take, but my experience is
that open source projects that succeed are those with developers that do not
have this attitude.

When I convince myself that I know what I'm doing, I'll throw together a
HOWTO about it. Meanwhile, if those who really do know what they are doing
would spend one hour over the next week writing a very simple HOWTO about
one of the things you know about (even if you just send it to the mailing
list with HOWTO in the title), it would sure make the lives of people like
me a lot easier, and would radically increase my confidence in Maven.

What would have helped me greatly over the last two weeks would be stuff
that would seem blatantly obvious to people who have been using Maven for a
while. Stuff like:

o How do you set up Maven to build a web application?
o How do you set up subprojects?
o How do you use Reactor? (And are dependencies from your project.xml
involved in using reactor? I still don't know.)
o What do you do when one of your subprojects does not support Maven?
o When you use Maven without a maven.xml file, what exactly happens? What
happens to that default process when a maven.xml file is added?
o A definitive list of all properties and what they do.
o The "correct" way to invoke plugins from maven.xml
o Using Jelly to do common things, like switch logic, or compare strings
case insensitively.

Simple trial and error, no more than 10-15 minutes will answer most of your questions. As for properties, the last I looked, they're documented in each plugin's docs which were (at least at one time) linked up on the maven site.

Simple stuff. Many people reading this message could write such documents in
minutes. As yet, I cannot, at least not with any confidence that I know what
I'm talking about.

--
To unsubscribe, e-mail:   <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>