maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephen Connolly <stephen.alan.conno...@gmail.com>
Subject Re: Little documentation issues
Date Tue, 09 Dec 2014 16:52:16 GMT
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 <rwheeler@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: rwheeler@artifact-software.com
> skype: ronaldmwheeler
> phone: 866-970-2435, ext 102
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message