> -----Original Message----- > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > Sent: mardi 31 octobre 2006 14:18 > To: Maven Users List > Subject: Re: Maven rant > > 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.
Sebastien, I don't believe this is true. This is the same as any open source project. It's not the community that creates an open source project. It's one or two guys (possibly 3 ;-)). Then once there is a strong kernel developed by these few guys then others will join and help. The same is true for documentation. You need one or 2 leaders to first write the core of it. This is what we've done with BBWM. Now I agree that a good idea could be to build on it by opening it up to the community. But don't believe a single instant that the community will write a good quality book by itself. BTW there's already a Maven wiki which is opened to anyone interested. It's been there for more than a year but I wouldn't call the result comprehensive documentation. Thanks -Vincent > 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] ___________________________________________________________________________ Découvrez une nouvelle façon d'obtenir des réponses à toutes vos questions ! Profitez des connaissances, des opinions et des expériences des internautes sur Yahoo! Questions/Réponses http://fr.answers.yahoo.com --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
