I totally agree but I think that the problem is very difficult to solve, especially with all the incredible amount of undeocumented features that Maven has. Moreover, the problem is amplified by the fact that Maven allows the generation of most of the documentation: but if you don't write it, it won't write itself, so you will endup with dead links everywhere.
As I see it, the problem in most Open Source projects is that developers do that on their free time, and developers aren't writers: those are two completely different tasks and the second one is not the most enjoyable. And last but not least: Open Source software is highly evolutive: why bother write some documentation for a feature that can be replaced by something more interesting in no-time and without any possible anticipation. The thing is that Maven is not the first Maven project I work with which faces that very issue. I had exactly the same problems a few months ago with Cocoon guys, and my remark is still the same: why do project leaders keep on considering documentation as a static thing. Think of Hibernate or PHP documentation: one base reference book with DYNAMIC comments in which people can share their thoughts and experiences about each feature/chapter, remarks that can be later integrated when the reference is rewritten. The problem is that, whereas development itself is a highly-collaborative and efficient process, nothing is really done so that documentation writing is collaborative enough: no workflow, no direct input, no dynamic comments, etc. Think of it: "Better Builds With Maven" is the most comprehensive documentation about Maven2. But was it written collaboratively? No. And I'm convinced that if it had been, it would be much higher quality and much more accessible today. Just my 2 cents. 2006/10/31, dhoffer <[EMAIL PROTECTED]>:
Jeff, I use maven and I really like it and I don't want this to sound like negative criticism but you are right, the learning curve for maven newbie's is huge and there just isn't much good docs available. I have wound up getting bits of pieces of info from here and there...it just takes so long. It would be great if some maven gurus could solve this problem and make maven more accessible. Jeff Mutonho wrote: > > Is maven in the process of unintentionally killing itself due to poor > support and documentation?I may be wrong but I strongly feel that the > poor support and documentation is hampering adoption of an otherwise > brilliant tool.It always seems like the participation of plugin > developers in answering questions from mere users like myself is > non-existent.Then lets not forget the poor documentation.The BB book > was an excellent idea ,but sometimes it just does not address problems > users face on the "setup battle field" and the "configuration > trenches" we're all familiar with.I'll give an example that relates to > my experience.I posted questions relating to problems with the Maven > Wagon plugin and in the process also thought it wise to see what the > documents say.That led me to http://maven.apache.org/wagon/ and > clicking on the Getting Started link I ended up at the URL > http://maven.apache.org/wagon/guides/getting-started/index.html , and > almost every link there leads to a : > ========================================================= > Page Not Found > Sorry, the page you requested was not found. This may because: > > * The page has moved, was outdated, or has not been created yet > * You typed the address incorrectly > * You following a link from another site that pointed to this page. > > We have recently reorganised our site, so please try looking in the > navigation on the left for the item you are looking for on Maven 1.x > or the Maven project. For information about Maven 2.0 or Continuum, > please visit their sub sites, available from the links in the top > right of the page. There is no need to report this broken link to the > Maven team, as errors are periodically monitored and repaired. > > =================================================================== > > Same thing happens with the "Examples" link.Surely this cannot be a > pleasant user experience for anyone , let alone for a poor newbie who > might think looking at the docs is a good start.In my example, what > then can a user do besides thinking of putting one's neck on the > guillotine?One gets no help on the mailing list and the documentation > isn't helpful either. > I understand very well the idea that people are busy etc , but also > feel that there's need for more participation from plugin authors in > helping mere users like myself and others who get stuck with problems > only the maven gurus can solve...unless of course the plugins are only > to be used by the authors themselves. > Please don't take take this as whining , but rather , as a personal > view and perhaps constructive criticism. > > -- > > > Jeff Mutonho > > GoogleTalk : ejbengine > Skype : ejbengine > Registered Linux user number 366042 > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > > -- View this message in context: http://www.nabble.com/Maven-rant-tf2544811s177.html#a7093319 Sent from the Maven - Users mailing list archive at Nabble.com. --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
-- Sébastien Arbogast http://www.sebastien-arbogast.com --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
