OTOH there's already open documentation on the Maven wiki and in Maven's svn. It's not because it's open that people contribute more or that the quality is better...
IMHO, Wiki is too open, SVN is not open enough. A CMS would be a middle-alternative allowing people to add remarks without modifying the original content. And only "committers" could decide to synthetize a few remarks and create a new version of the content. I totally agree with you: it's not because it's open that people contribute more or that the quality is better... but with the right tools and methods, it's exactly what happens. Think of how Open Source software works: anybody can propose patches, only committers can apply them. With such an open documentation effort, everybody could submit comments, only committers could rewrite sections to integrate those remarks. PHP project has been doing that for years and their documentation is wonderful: even non-committed comments are useful because they offer very pragmatic and issue-driven answers to specific problems. We had exactly the same discussion last year with Cocoon community when Mark Leicester and I tried to start an open documentation effort for Cocoon (http://www.planetcocoon.com). I've always thought that Apache's projects documentation could greatly benefit from such an open approach for documentation.
> -----Original Message----- > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > Sent: dimanche 16 juillet 2006 21:39 > To: Maven Users List > Subject: Re: Maven book: feedback > > Why not trying to innovate then? Why not getting the source code of > the book available to the community and make its improvement a > community effort? It could be an interesting experiment: using the > current version as a working basis, you could allow people to pinpoint > parts that could be improved, and others could propose rewritten > sections. > > Technically, you could use a CMS, with one page for each subsection of > the book, and people could leave comments about each section. > Sometimes people could gather several remarks and rewrite the section > to take them into account, thus creating a new version of the section. > And that way, the book would be more dynamic andit would be easier to > update it as Maven evolves. I've already done that kind of things with > Drupal and it gave quite good results. > > What do you think ? Open Source documentation ? > > 2006/7/16, Vincent Massol <[EMAIL PROTECTED]>: > > Hi Sebastien, > > > > I'm glad that you liked the m1 book ;-) but I'm sorry that you don't > like > > the new m2 one... > > > > There are probably several reasons. One of them may be that it's hard to > > write with a consistent voice and consistent progression when several > > authors write at the same time. OTOH this has allowed us to cover an > > important variety of topics and to release the book when it was needed. > > > > I guess the other hard part when we wrote the m2 book is that m2 was and > > still is evolving. This is one reason why an online format is a good > choice. > > > > So I guess that in order to improve in the next release of the m2 book > we > > should get someone to review/reorder/rewrite the junctions between the > > different chapters to get a more seamless flow between them and so that > the > > progression remains constant. What would make this even easier would be > to > > get help from the community to tell us precisely where things should be > > improved. > > > > AFAIK there's no Maven2 Developer's Notebook in the pipeline and I think > we > > should be able to improve this one over time. It's an online book and > thus > > has the power of being modified more easily. > > > > Thanks for your feedback. > > -Vincent > > > > > -----Original Message----- > > > From: Sebastien Arbogast [mailto:[EMAIL PROTECTED] > > > Sent: samedi 15 juillet 2006 18:11 > > > To: Maven users list > > > Subject: Maven book: feedback > > > > > > Hi, > > > > > > I'm currently in the process of reading "Better builds with Maven" and > > > to be honnest... I'm quite disappointed. I found "Maven Developer's > > > notebook" for Maven 1 excellent, and I said it a few times on this > > > list. It's even one of the books I used the most often for some time. > > > And when Vincent Massol announced at JavaPolis in last december that a > > > free Maven2 book was on its way, I was very excited, because I dreamt > > > of such a good book combined with all the marvels of Maven2 that he > > > demonstrated. > > > > > > When I started reading "Better Builds with Maven" for the first time, > > > just after it was released, I was quickly annoyed by the number of > > > errors and the inconsistence of sample source code with what was > > > reproduced in the book. So I waited for the updated version with > > > corrected errata and I'm reading it right now... and I'm somewhat > > > disappointed because it puzzles me more than anything. > > > > > > It starts off with a very basic introduction to what is Maven, how it > > > was designed... and suddenly, it jumps straight up to web services and > > > very elaborated samples that have nothing to do with a progressive and > > > pragmatic approach. Even worse: samples are full of noise concerning > > > exotic plugins and their configuration and the structure is very... > > > weird. > > > > > > I'm not into free criticism, but I think feedback is important, even > > > when it's negative. And based on that, I would like to know if there > > > is a Maven2 Developer's Notebook in the pipeline, something more > > > pragmatic, something simpler, something that would give justice to the > > > beauty of Maven2. Because I'm afraid this one could frighten new users > > > more than encourage them to abandon their old Ant scripts. Because I > > > would even be ready to pay a few tens of bucks just to get the same > > > experience I had with the first O'Reilly volume. And because > > > obviously, I miss a lot of knowledge to write it myself. > > > > > > Once again, don't take me wrong: this is not free criticism, this is > > > just my humble yet negative feedback as a user who's been using Maven1 > > > for about a year and a half on personal and professional projects, and > > > who's looking for an efficient and comprehensive reference book to > > > migrate to Maven 2 and understand its changes pragmatically and > > > progressively. > > > > > > -- > > > Sébastien Arbogast > > > > > > http://www.sebastien-arbogast.com > > > > > > --------------------------------------------------------------------- > > > To unsubscribe, e-mail: [EMAIL PROTECTED] > > > For additional commands, e-mail: [EMAIL PROTECTED] > > > > > > > > > > > > > > > __________________________________________________________________________ > _ > > Yahoo! Mail réinvente le mail ! Découvrez le nouveau Yahoo! Mail et son > interface révolutionnaire. > > http://fr.mail.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] ___________________________________________________________________________ Yahoo! Mail réinvente le mail ! Découvrez le nouveau Yahoo! Mail et son interface révolutionnaire. http://fr.mail.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]
