> 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. 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. 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. 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".) 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 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]>
