maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ron Wheeler <rwhee...@artifact-software.com>
Subject Little documentation issues
Date Tue, 09 Dec 2014 16:42:14 GMT
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