maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ron Wheeler <rwhee...@artifact-software.com>
Subject Re: New site content
Date Fri, 03 Jan 2014 17:19:36 GMT
https://cwiki.apache.org/confluence/display/MAVEN/Tutorial%3A+Maven+in+60+seconds
Still think that it is overly vague.

It would be easier to understand if the passive voice was eliminated. 
Makes it clearer to understand what the developer has to do and what 
maven is going to do while processing the POM.

The page should start with a statement saying that Maven builds 
artifacts based on information provided by the developer.

You might want to talk about convention over configuration and how this 
compares to Make or Ant.

"It all starts with a *project model"* ->"It all starts with a *project 
model* that you create to tell Maven how you want your project (artifact?)."

/Note: reactor is just the name that Maven has given to the list of 
modules that are being built
/Is module different than artifact? Are modules input or output?
See below for confusion about whether a reactor is a list or a thing 
that does stuff./
/
The *packaging* of each module (artifact?) implies that modules are 
output - should provide example "such as jar, war, tar or zip" (90 
percent of cases?)

"The *dependencies* of each module" => "The dependencies that are 
required to build, test and run the resulting  project/module/artifact."

"Any additional *plugins* that are needed to build each module" => "Any 
*plugins* that are needed to build each module."
  What does additional mean to the new user?
Perhaps a sentence about default plug-ins that Maven includes 
automatically might be useful but conceptually I don't think that the 
distinction is useful at this point

"The lifecycle defines the default plugins that are used to build a 
specific packaging. "
This is a bit startling to a new user even if it is correct.
It might be better to describe the lifecycle in terms of steps rather 
than plug-ins.
It might also be worth being explicit that lifecycles are defined in 
Maven not in the model.

These next 2 sentences need to be rewritten in the active case saying 
that Maven does these things.

"The list of modules in the reactor is sorted in order to ensure that 
any dependencies that will be created by the reactor will be built 
before they are needed by other modules in the reactor
The *build plan* is then populated for each module using the lifecycle 
and the plugin information from the model"

Build plan is not defined. Who creates it? What does it have in it 
before it is populated? How many build plan are there - one for each 
module?/ one for all?.
Should say that a single build plan is created that builds the 
xxxx(components - no definition in the diagram of what the programmer 
has programmed) in the correct sequence.

Maven then starts executing the build plan and building your project, 
downloading dependencies that are not produced by the reactor.
A reactor was defined as a list of modules, now it is a thing that does 
produced dependencies.

Final diagram is missing the output from the process.
It seems to say that Maven builds "Build Plans"(square box).
The developer wants an artifact out of this.

I hope that this helps.

Ron



On 03/01/2014 11:33 AM, Stephen Connolly wrote:
> FYI here is my current plan for content:
>
> https://cwiki.apache.org/confluence/display/MAVEN/New+Main+Site
>
>
> On 3 January 2014 16:27, Ron Wheeler <rwheeler@artifact-software.com 
> <mailto:rwheeler@artifact-software.com>> wrote:
>
>     I agree with Robert's comment.
>     There is a danger that the page will become architecturally
>     elegant and will correctly describe all of the possible uses of
>     Maven but will be too obscure to be useful as a starting point for
>     a new person.
>
>
> I actually think that the page is near complete from my point of 
> view... the remaining content is actually to provide links to pages 
> describing what each individual concept is and a link to the next 
> level of depth tutorial.
>
> I what to draw only the outline of what maven does... on the other 
> hand, if you can think of an alternative set of content I am only too 
> happy to see such suggestions. If you need write access to the wiki, 
> shout out and I'll make it so (assuming you are a regular user/dev 
> list contributor)
>
>
>     It is sufficiently difficult to understand the basic concepts in
>     using Maven to create a simple jar with a single POM.
>     You are introducing a lot of new concepts:
>     -Lifecycle
>     -Dependencies
>     -Plug-ins
>     - Project model
>     that a person coming from make or Ant has to grasp.
>
>     Defining these and the relationships among them in a simple way is
>     sufficiently challenging without trying to abstract a sufficiently
>     general model to handle all of the edge cases.
>
>     The "Maven way" needs to be explained very simply rather than
>     conceptually complete.
>
>     Ron
>
>
>
>     On 03/01/2014 11:09 AM, Robert Scholte wrote:
>
>         Op Fri, 03 Jan 2014 16:46:33 +0100 schreef Stephen Connolly
>         <stephen.alan.connolly@gmail.com
>         <mailto:stephen.alan.connolly@gmail.com>>:
>
>             On 3 January 2014 15:17, Robert Scholte
>             <rfscholte@apache.org <mailto:rfscholte@apache.org>> wrote:
>
>                 Hi,
>
>                 I like the idea of images, however I would avoid a
>                 graph to make something
>                 clear for new Maven users.
>                 Instead I'd prefer a linear model.
>
>
>             My first draft did not have the graph at the top...
>             perhaps it would be
>             better suited at the bottom ;-)
>
>
>
>                 I think you should split the current model into pieces:
>
>                 A project model contains:
>                 - dependencies
>                 - a build plan
>                 - other project models ( you can call this the Droste
>                 effect[1] )
>
>
>             I like to think of the project model as not just the root
>             pom.xml but all
>             the pom.xml files, so there is only one project model,
>             this should make
>             understanding how -pl, -am and -amd switches have their
>             effects
>
>
>
>         IMO these switches are way too detailed for a 60 sec tutorial.
>         I even think that a large group of the average Maven users
>         don't know these switches or use them.
>
>                 - ...
>
>                 There are several build-plans, namely: a build-plan
>                 for jar, war, ear, etc.
>                 Every build plan has a set of predefined plugins,
>                  which you can adjust
>                 (with switches?)
>
>
>             No there is one and only one build plan. We would have to
>             redefine build
>             plan everywhere else to be able to use it like that. There
>             is a lifecycle
>             binding for each packaging
>
>
>
>         Then buildplan is too abstract. With a real world example: the
>         buildplan for a house and a bike are completely different.
>         Unless you say: you have a design, some goods, you mix those
>         goods and you have your product.
>         Not a useful plan IMO.
>         At least keep the audience in mind: do they need to know the
>         actual implementation or do they first need to understand the
>         overall process. I think the latter is more important, even if
>         this conflicts a bit with the idiom used by experienced Maven
>         users.
>         What if we call it "build instructions" (per packaging type) ?
>
>
>                 Now, what does Maven do?
>
>                 Maven reads the build plan and executes it. Some steps
>                 of the build plan
>                 deliver products ( compiled classes, test results, a
>                 package)
>
>                 I think the reactor might be confusing at this level.
>
>
>             I want the 60sec tutorial to be the grand overview, the
>             next tutorial is a
>             5 minute one on how a .jar file gets built
>
>             Then you have a multi-module webapp tutorial at 10-15min
>
>             I want to reference all the core concepts from the 60
>             second overview even
>             if only briefly, that way people can come back to the
>             short page and say
>             "ahh yes that is where that fits in again"
>
>
>
>                 my 2 cents,
>
>                 Robert
>
>                 [1] http://en.wikipedia.org/wiki/Droste_effect
>
>
>                 Op Fri, 03 Jan 2014 15:41:15 +0100 schreef Stephen
>                 Connolly <
>                 stephen.alan.connolly@gmail.com
>                 <mailto:stephen.alan.connolly@gmail.com>>:
>
>
>                  Just in case it wasn't clear... I'm looking for
>                 comments and feedback
>
>
>
>                     On 3 January 2014 14:35, Stephen Connolly
>                     <stephen.alan.connolly@gmail.com
>                     <mailto:stephen.alan.connolly@gmail.com>>wrote:
>
>                      OK, so to start working on new content I created
>                     some pages on the wiki:
>
>
>                         The first page is a 60 seconds overview of
>                         Maven's build process
>
>
>                         https://cwiki.apache.org/confluence/display/MAVEN/
>                         Tutorial:+Maven+in+60+seconds
>
>                         I am using icons because I want to have
>                         subsequent pages give more detail
>                         and use the iconography to enable people to
>                         see what is being discussed
>                         more easily
>
>
>         ---------------------------------------------------------------------
>         To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
>         <mailto:users-unsubscribe@maven.apache.org>
>         For additional commands, e-mail: users-help@maven.apache.org
>         <mailto:users-help@maven.apache.org>
>
>
>
>
>     -- 
>     Ron Wheeler
>     President
>     Artifact Software Inc
>     email: rwheeler@artifact-software.com
>     <mailto:rwheeler@artifact-software.com>
>     skype: ronaldmwheeler
>     phone: 866-970-2435, ext 102
>
>
>     ---------------------------------------------------------------------
>     To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
>     <mailto:users-unsubscribe@maven.apache.org>
>     For additional commands, e-mail: users-help@maven.apache.org
>     <mailto:users-help@maven.apache.org>
>
>


-- 
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