> -----Original Message----- > From: Sebastien Brunot [mailto:[EMAIL PROTECTED] > Sent: jeudi 2 novembre 2006 10:26 > To: Maven Users List > Subject: RE: Maven rant > > I'm just joining, but what about creating a wiki with the entire free > maven book content so that the (user) community can update it ? I agree > to the fact that you need some predefined structure to ensure effective > documentation by users / developers. Adding a snipet of documentation > should be a "no cost" operation, and having a predefined structure may > help to achieve this goal.
This would be good but it's a choice to be made by Mergere (the publisher of the book). Thanks -Vincent > -----Original Message----- > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > Sent: Tuesday, October 31, 2006 2:45 PM > To: Maven Users List > Subject: Re: Maven rant > > 2 thoughts about what you wrote Vincent: > > I totally agree on the fact that a few people have to write the core of > the documentation before any community effort can be considered. > But at some point, a PDF and an errata page is not the best way to > create a community effort in order to keep this book up-to-date and > more accessible. > > This leads me to the second point: Maven's wiki doesn't work for the > very same reason Cocoon one didn't, for the very same reason I've never > seen one good documentation effort based solely on a WIKI: no > structure! And that's exactly what your book could be useful as: some > sort of a spinal cord on which other content can be aggregated and > accumulated over time, and sometimes assimilated on a rewrite. > Moreover, I don't believe in Wikis at all because instead of adding > some information, it just replaces it, even if it keeps some kind of > version tracking behind the scenes. > > IMHO, Maven documentation should look like that: > http://drupal.org/handbooks > > 2006/10/31, Vincent Massol <[EMAIL PROTECTED]>: > > > > > > > -----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] > > > > > > > -- > Sébastien Arbogast > > http://www.sebastien-arbogast.com > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > > --------------------------------------------------------------------- > 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]
