Hi, I've been reading this thread with interest.
> No it's not a catch 22. I will clarify what I was saying in my other > statement. People have exactly 2 choices when faced with a problem such as > documentation. The first one is to say, "Boy this product is too hard for > me to learn and there isn't enough documentation, so I'll go find something > else." The second option is to say, "Boy this product is hard, but I really > think it could help me on my product so I will learn how to use it and ask > questions on the list. Then, because I had so much trouble starting, I will > recontribute back what I learned to the project." No one is forcing anyone > to do anything. That's the beauty and bane of free software. In order for > it to be free, someone has to invest THEIR time to provide you the free > software. If you don't like it, you can move on without losing a monetary > investment. The bane is that because the contributers/developers aren't > usually getting paid, they have to have other jobs where they make their > living. To demand that they make sure you get the documentation that you > want rather than keep up with regular features for others that don't need > the documentation isn't fair either. Others like me have been fine without > the documentation, so the question is more why have some succeeded and > others failed? In my opinion, those that have succeeded with mvn have been 1 of 2 types: 1 - using mvn for simple tasks 2 - mvn developers I currently have a project I'm working on which has a multi-stage build and requires several 3rd-party mvn plugins. Getting this to work correctly has been a nightmare - there's no other way of describing the frustration with the lack of documentation of the core of mvn. Now we also had some specialised requirements (as is often the case), so I've had to write and maintain 4 custom plugins for our build. So from last November (mvn newbie) to now I've done a considerable amount of mvn hacking, including supplying patches for plugins and writing new plugins. mvn internally has appalling docs, there's practically no javadoc in the project - this makes writing patches to mvn itself tedious and frustrating - and *I want to get involved*. For someone who isn't interested in getting involved, but they need to fix a bug in mvn (and yes mvn has bugs), they open the sources and see undocumented code - that's a massive turn off. Perhaps I'm in the minority, but the mvn mailing lists (users/dev) are not the source of answers I thought they would be - I've asked a few questions on how to configure a plugin/build to achieve the output I wanted - and no there wasn't a reply with an answer. Here is an example: The mvn-war-plugin (which combined with the jspc-plugin should allow me to only create a war with .class files (no jsps included)). By default, this plugin includes everything, so setting warSourceExcludes to exclude the jsp files is the solution - except it isn't. If you set warSourceExcludes to exclude the unnecessary jsp files, it still includes the empty dirs that the jsps were in - this makes my war larger than it should be. If I manually specify exactly what to include I get a massive warSourceIncludes section (which must be repeated in each profile as mvn & plexus don't support xml entity fragments eg &warSources;) I'd like to modify the mvn-war-plugin source to exclude empty dirs, but again the code isn't well documented and I'd have to maintain a custom version of this plugin instead of using the normal one available on ibiblio/maven2 (I already maintain a custom jspc plugin as it's being re-written in groovy at the moment and is dependent on a broken version of ant which has a URI bug) > It's a big short sighted to even assume that someone would say, "Go pour > through the source and write documentation." That's also quite a bit overly > dramatic. If I had to pour through source in order to learn how to use > Maven, I would have sucked it up and moved on. Welcome to my world - to get anything done (writing mvn plugins, fixing bugs in plugins we use etc), this is exactly what I have to do - and no it isn't overly dramatic, I have to read the src for various plugins and mvn just to work out what is happening as there are no API docs. Often the plugin svn repo has changed location and the site hasn't been updated, so then you have to hunt down the correct svn location using trial and error - again this is a doc issue (jspc plugin had exactly this problem) > Once again I reiterate, if > you take it step by step then you will be fine. Ant is NOT any easier to > create a build system with. In my experience Ant is much more easy to make a build system, but to each his own > For non multiproject builds, there is no reason > that someone shouldn't be able to read the getting started and have a webapp > up in a few minutes. The problem is that people use mvn to begin with, with a simple project and think 'wow it's so easy', then when used in more complex circumstances, the documentation falls flat and the non-dedicated, willing-to-peruse-src-code user will be put off. I'm looking forward to see what other people think, Kev --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
