Hmmmm that seems to have failed to sync since.... scratch that...
On 9 December 2014 at 16:52, Stephen Connolly < stephen.alan.conno...@gmail.com> wrote: > Do you want to create some pull requests? > https://github.com/apache/maven-site is the repo... we can take care of > pulling those patches back to SVN, so no need to worry about that part ;-) > > On 9 December 2014 at 16:42, Ron Wheeler <rwhee...@artifact-software.com> > wrote: > >> After using maven for 7+years, I decided that I finally knew enough about >> it to read the docs. >> I started here - http://maven.apache.org/guides/getting-started/index. >> html - and this led to other pages. >> >> I have found some places where a little cleaning up might help new users. >> There is one BIG issue and a few smaller ones. >> >> 1) http://maven.apache.org/guides/introduction/ >> introduction-to-the-lifecycle.html >> 1a) >> "Packaging >> >> The first, and most common way, is to set the packaging for your project >> via the equally named POM element <packaging>. Some of the valid packaging >> values are jar, war, ear and pom. >> " >> Could we have the full list here or a link to a page with the full list >> of the "normal" ones? >> Could we have a mention that plug-ins can provide new packaging. There is >> an example after the table of the Plexus. This discussion would be better >> if held together rather than split up with a discussion of binding and a >> table between the two parts of the story. >> >> >> 1b) In the table following this line "Each packaging contains a list of >> goals to bind to a particular phase. For example, thejarpackaging will bind >> the following goals to build phases of the default lifecycle." a heading >> row would be nice. >> >> 1c) >> Plugins are mentioned well before they are defined on the page. It would >> be helpful to briefly describe what a plugin is before using it as a known >> concept in "A Build Phase is Made Up of Plugin Goals" which never defines >> it before dropping "And this is done by declaring the plugin goals bound to >> those build phases." >> 1d) >> The definition of plug-in is obscure to say the least "Plugins are >> artifacts that provide goals to Maven." Surely there must be a clearer way >> to describe the concept of plugin. >> This is one of the most important Maven concepts and this is a WTF >> definition. >> >> 2) http://maven.apache.org/guides/getting-started/index.html >> >> 2a)How can Maven benefit my development process? -> How can Maven be of >> benefit to my development process? -> How can Maven improve my development >> process? >> More common English usage although the current wording is not wrong >> 2b) How do I use plug-ins? -> How do I use plugins? no hyphen in >> plug-in. Whoops plugin! >> >> 2c) How do I use plugins? has no description of what a plugin is. >> >> 3) http://maven.apache.org/guides/mini/guide-configuring-plugins.html >> >> 3a) No definition of what a plugin is; it just starts of with the >> assertion that there are 2 types. I am not sure that that statement is >> really true or if it is, it is not a very useful categorization. >> >> 3b) It is recommended to always defined each version of the plugins used >> by the build to guarantee the build reproducibility. -> It is recommended >> the version of the each plugins used by the build is specified to guarantee >> the reproducibility of the build. >> A good practice is to specify them in >> the<build><pluginManagement/></build>elements >> for*each*build plugins (generally, you will define a <pluginManagement/> >> element in a parent POM). -> >> It is a good practice to specify the version in >> the<build><pluginManagement/></build>element for*each*plugin. The >> <pluginManagement/> element is generally specified in a parent POM so that >> the same plugin version is use in all related projects. >> >> c) "Maven plugins (build and reporting) are configured by specifying >> a<configuration>element where the child elements of >> the<configuration>element are mapped to fields, or setters, inside your >> Mojo (remember that a plug-in consists of one or more Mojos where a Mojo >> maps to a goal). " >> Remember!!!. This is the first time a Mojo has been mentioned. It has no >> definition and if I look it up I get: >> >> "mo·jo1 >> 'mojo/ >> nounUS >> a magic charm, talisman, or spell. >> "someone must have their mojo working over at the record company" >> magic power. >> synonyms: magic, voodoo, hoodoo, wizardry, sorcery; >> " >> >> No wonder my builds aren't working! >> >> >> >> Can these be fixed soon. >> >> Some of them are just little bugs but the lack of a clear definition and >> discussion of plugins at the beginning of the "Getting Started" >> documentation is a really big oversight since so much of Maven depends on >> the built-in plugins and plugins that are created for special tasks. >> >> Now that we have a new logo and persona, it is time to fix the docs to >> make them more accessible. >> >> Is there a chance that I may eventually understand Maven! >> >> Ron >> >> >> >> >> -- >> Ron Wheeler >> President >> Artifact Software Inc >> email: rwhee...@artifact-software.com >> skype: ronaldmwheeler >> phone: 866-970-2435, ext 102 >> >> >
