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 <[email protected]> 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: [email protected] > skype: ronaldmwheeler > phone: 866-970-2435, ext 102 > >
