Hello, first of all, thanks for your replies. I think it would help very much if an introductory would be at the plugin development page[1] to get the big picture. Or even be repeated at the the run[2] page.
Running Maven is trivial until you encounter problems or wish to extend stuff. I deal a lot with supporting our department (roughly 200 developers, 150 of whom are using Maven) and I am always reiterating explaining the basic glossary (phase, lifecycle, goal). While the "Complete reference" by Sonatype is great once you know the basics, it is quite extensive and not every application developer wants or needs to delve throught it :-) Regards Mirko [1] http://maven.apache.org/guides/plugin/guide-java-plugin-development.html [2] http://maven.apache.org/run-maven/index.html#Quick_Start Regards Mirko -- http://illegalstateexception.blogspot.com/ https://github.com/mfriedenhagen/ https://bitbucket.org/mfriedenhagen/ On Sun, Jul 7, 2013 at 4:14 PM, Lennart Jörelid <lennart.jore...@gmail.com> wrote: > Well ... first of all, if documentation is considered important or > relevant, it should be easy to find. > The first principle of design is to make the function/use of an object > visible. > > Currently, the main maven documentation for practically everyone (except, > perhaps, maven > developers who digs around in the code quite a bit), is found at > > http://maven.apache.org/ > > ... and it is quite difficult to find your way from that page to the > description of core concepts. > For starters, one would have to know that the description of lifecycles is > documented in maven-core. > > From a usability standpoint, I think that the start page could benefit > greatly from being cleaned up. > At the moment it contains a huge amount of links, and the structure of the > maven site is not apparent - > especially for a newcomer. Moreover, in terms of readability and usability > I think we can learn from > the TomEE example - refer, for example to the > http://tomee.apache.org/documentation.html page for > structuring and classifying information. > > I would argue that using twitter bootstrap mechanics for achieving readable > and usable sites would > be quite healthy for the Maven main site. > > > > 2013/7/7 Hervé BOUTEMY <herve.bout...@free.fr> > >> yes, such doc is useful IMHO, since it took myself a lot of time to get it >> clear in my mind (particularly lifecycle->phase->goal) >> >> for the moment, I didn't find energy to write it down since I didn't know >> where >> to put it to get us work on improvements (and even if anybody would find it >> useful) >> >> it's probably a good time to work on it >> >> for the moment, I imagine putting such a desdcription (=Maven as a build >> tool) >> in maven-core artifact site [1] >> >> any other idea? >> >> Regards, >> >> Hervé >> >> [1] http://maven.apache.org/ref/3-LATEST/maven-core/ >> >> Le dimanche 7 juillet 2013 12:59:05 Stéphane Nicoll a écrit : >> > Maybe worth understanding why the current online documentation did not >> > helped you. And maybe update it with this. >> > >> > Thanks. >> > >> > Sent from my iPhone >> > >> > On 07 Jul 2013, at 12:51, "Lennart Jörelid" <lennart.jore...@gmail.com> >> wrote: >> > > Hello there Mirko, >> > > >> > > I'd suggest fine-tuning the lifecycle->phase->plugin description >> slightly: >> > > - Maven is a tool to build software, which relies mainly on >> conventions. >> > > - The build is configured in an XML file called pom (project object >> > > model, or "pom file"). >> > > - Maven consists of a core and a plethora of plugins. Plugins can be >> > > included in the build by being configured within the pom file. >> > > - Maven builds stuff (often binaries) according to recipes outlined >> > > >> > > in lifecycles. >> > > >> > > Predefined lifecycles are called "default", "clean" and "site". >> > > - Lifecycles consist of sequences of named steps, called phases. The >> > > names of all phases are standarized, such as "compile", "test" or >> > > "install". - When Maven executes a phase, it announces the phase name >> > > to all >> > > plugins included in the build. >> > > - Plugins contain methods which perform specific actions like e.g. >> > > compiling java source to classes or running unit tests. These methods >> > > are given a symbolic name, called "goal", and configured to run >> within a >> > > specified phase (known as "binding" a goal to a phase). >> > > - There are standard definitions which goals should be run during a >> > > phase >> > > of a lifecycle and this is mostly dependent on the packaging, the >> type >> > > of binary produced. It makes no big sense to run the compiling goal >> for >> > > java sources on a project which contains images but no source code, >> for >> > > example. >> > > >> > > 2013/7/7 Mirko Friedenhagen <mfriedenha...@gmail.com> >> > > >> > >> Hello, >> > >> >> > >> I did not find an overview and now am trying to explain firstly myself >> > >> and afterwards maybe others how Maven works (to other developers): >> > >> >> > >> - Maven is a declarative tool to build software, which relies mainly >> > >> on conventions. >> > >> - Declarations are done in a XML file called pom (project object >> model). >> > >> - Maven consists of a small core and a plethora of plugins. >> > >> - Maven builds stuff (often binaries) following paths outlined in >> > >> lifecycles, predefined lifecycles are called "default", "clean" and >> > >> "site". >> > >> - Lifecycles are sequences of phases like e.g. compile, test or >> install. >> > >> - Plugins provide a multitude of so called goals, which do specific >> > >> stuff like e.g. compiling java source to classes or running unit >> > >> tests. >> > >> - The execution of goals is often bound to lifecycle phases. >> > >> - There are standard definitions which goals should be run during a >> > >> phase of a lifecycle and this is mostly dependent on the packaging, >> > >> the type of binary produced. It makes no big sense to run the >> > >> compiling goal for java sources on a project which only holds a pom, >> > >> which is a XML file. >> > >> >> > >> Regards Mirko >> > >> -- >> > >> http://illegalstateexception.blogspot.com/ >> > >> https://github.com/mfriedenhagen/ >> > >> https://bitbucket.org/mfriedenhagen/ >> > >> >> > >> --------------------------------------------------------------------- >> > >> To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >> > >> For additional commands, e-mail: dev-h...@maven.apache.org >> > > >> > > -- >> > > >> > > -- >> > > +==============================+ >> > > >> > > | Bästa hälsningar, >> > > | [sw. "Best regards"] >> > > | >> > > | Lennart Jörelid >> > > | EAI Architect & Integrator >> > > | >> > > | jGuru Europe AB >> > > | Mölnlycke - Kista >> > > | >> > > | Email: l...@jguru.se >> > > | URL: www.jguru.se >> > > | Phone >> > > | (skype): jgurueurope >> > > | (intl): +46 708 507 603 >> > > | (domestic): 0708 - 507 603 >> > > >> > > +==============================+ >> > >> > --------------------------------------------------------------------- >> > To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >> > For additional commands, e-mail: dev-h...@maven.apache.org >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org >> For additional commands, e-mail: dev-h...@maven.apache.org >> >> > > > -- > > -- > +==============================+ > | Bästa hälsningar, > | [sw. "Best regards"] > | > | Lennart Jörelid > | EAI Architect & Integrator > | > | jGuru Europe AB > | Mölnlycke - Kista > | > | Email: l...@jguru.se > | URL: www.jguru.se > | Phone > | (skype): jgurueurope > | (intl): +46 708 507 603 > | (domestic): 0708 - 507 603 > +==============================+ --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
