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:53:01 GMT
Hmmmm that seems to have failed to sync since.... scratch that...


On 9 December 2014 at 16:52, Stephen Connolly <
stephen.alan.connolly@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 <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