I've been wondering how to apply "explanations" to things. With ActiveMQ and Camel I just edit the Confluence wiki. If I can issue a GitHub pull request and see the change within a day or two that's fine.
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 > > > > >
