You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@maven.apache.org by Sebastien Brunot <sb...@ilog.fr> on 2006/11/02 10:25:52 UTC
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.
Sebastien
-----Original Message-----
From: Sebastien Arbogast [mailto:sebastien.arbogast@gmail.com]
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 <vi...@massol.net>:
>
>
> > -----Original Message-----
> > From: Sebastien Arbogast [mailto:sebastien.arbogast@gmail.com]
> > 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 <DH...@xrite.com>:
> > >
> > > 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: users-unsubscribe@maven.apache.org
> > > > For additional commands, e-mail: users-help@maven.apache.org
> > > >
> > > >
> > > >
> > >
> > > --
> > > 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: users-unsubscribe@maven.apache.org
> > > For additional commands, e-mail: users-help@maven.apache.org
> > >
> > >
> >
> >
> > --
> > Sébastien Arbogast
> >
> > http://www.sebastien-arbogast.com
> >
> > --------------------------------------------------------------------
> > - To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> > For additional commands, e-mail: users-help@maven.apache.org
>
>
>
>
>
>
> ______________________________________________________________________
> _____ 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: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
--
Sébastien Arbogast
http://www.sebastien-arbogast.com
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
RE: Maven rant
Posted by Vincent Massol <vi...@massol.net>.
> -----Original Message-----
> From: Sebastien Brunot [mailto:sbrunot@ilog.fr]
> 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:sebastien.arbogast@gmail.com]
> 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 <vi...@massol.net>:
> >
> >
> > > -----Original Message-----
> > > From: Sebastien Arbogast [mailto:sebastien.arbogast@gmail.com]
> > > 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 <DH...@xrite.com>:
> > > >
> > > > 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: users-unsubscribe@maven.apache.org
> > > > > For additional commands, e-mail: users-help@maven.apache.org
> > > > >
> > > > >
> > > > >
> > > >
> > > > --
> > > > 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: users-unsubscribe@maven.apache.org
> > > > For additional commands, e-mail: users-help@maven.apache.org
> > > >
> > > >
> > >
> > >
> > > --
> > > Sébastien Arbogast
> > >
> > > http://www.sebastien-arbogast.com
> > >
> > > -------------------------------------------------------------------
> -
> > > - To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> > > For additional commands, e-mail: users-help@maven.apache.org
> >
> >
> >
> >
> >
> >
> >
> ______________________________________________________________________
> > _____ 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: users-unsubscribe@maven.apache.org
> > For additional commands, e-mail: users-help@maven.apache.org
> >
> >
>
>
> --
> Sébastien Arbogast
>
> http://www.sebastien-arbogast.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
___________________________________________________________________________
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: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
RE: Maven rant
Posted by Sebastien Brunot <sb...@ilog.fr>.
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:sebastien.arbogast@gmail.com]
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 <sb...@ilog.fr>:
> 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:sebastien.arbogast@gmail.com]
> 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 <vi...@massol.net>:
> >
> >
> > > -----Original Message-----
> > > From: Sebastien Arbogast [mailto:sebastien.arbogast@gmail.com]
> > > 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 <DH...@xrite.com>:
> > > >
> > > > 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: users-unsubscribe@maven.apache.org
> > > > > For additional commands, e-mail: users-help@maven.apache.org
> > > > >
> > > > >
> > > > >
> > > >
> > > > --
> > > > 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: users-unsubscribe@maven.apache.org
> > > > For additional commands, e-mail: users-help@maven.apache.org
> > > >
> > > >
> > >
> > >
> > > --
> > > Sébastien Arbogast
> > >
> > > http://www.sebastien-arbogast.com
> > >
> > > ------------------------------------------------------------------
> > > --
> > > - To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> > > For additional commands, e-mail: users-help@maven.apache.org
> >
> >
> >
> >
> >
> >
> > ____________________________________________________________________
> > __ _____ 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: users-unsubscribe@maven.apache.org
> > For additional commands, e-mail: users-help@maven.apache.org
> >
> >
>
>
> --
> Sébastien Arbogast
>
> http://www.sebastien-arbogast.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
--
Sébastien Arbogast
http://www.sebastien-arbogast.com
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org
Re: Maven rant
Posted by Sebastien Arbogast <se...@gmail.com>.
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 <sb...@ilog.fr>:
> 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:sebastien.arbogast@gmail.com]
> 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 <vi...@massol.net>:
> >
> >
> > > -----Original Message-----
> > > From: Sebastien Arbogast [mailto:sebastien.arbogast@gmail.com]
> > > 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 <DH...@xrite.com>:
> > > >
> > > > 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: users-unsubscribe@maven.apache.org
> > > > > For additional commands, e-mail: users-help@maven.apache.org
> > > > >
> > > > >
> > > > >
> > > >
> > > > --
> > > > 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: users-unsubscribe@maven.apache.org
> > > > For additional commands, e-mail: users-help@maven.apache.org
> > > >
> > > >
> > >
> > >
> > > --
> > > Sébastien Arbogast
> > >
> > > http://www.sebastien-arbogast.com
> > >
> > > --------------------------------------------------------------------
> > > - To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> > > For additional commands, e-mail: users-help@maven.apache.org
> >
> >
> >
> >
> >
> >
> > ______________________________________________________________________
> > _____ 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: users-unsubscribe@maven.apache.org
> > For additional commands, e-mail: users-help@maven.apache.org
> >
> >
>
>
> --
> Sébastien Arbogast
>
> http://www.sebastien-arbogast.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> For additional commands, e-mail: users-help@maven.apache.org
>
>
--
Sébastien Arbogast
http://www.sebastien-arbogast.com
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org