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.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]
