I agree that the problem may be faced, but what about trying it the agile way : just putting everything online in a new wiki instance, and waiting a few month to see which how it evolves ?
Sebastien (the other one ;-) -----Original Message----- From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] Sent: Thursday, November 02, 2006 10:31 AM To: Maven Users List Subject: Re: Maven rant But you won't solve the main issue of a wiki system: information replacement. I still think that a comment system would be more reliable on the long term. 2006/11/2, Sebastien Brunot <[EMAIL PROTECTED]>: > 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. > > Sebastien > > -----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.htm > > > > > l > > > > > , > > > 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] > > -- 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]
