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: New site content
Date Fri, 03 Jan 2014 16:56:00 GMT
Also, in case it is not clear, my preferred style is to tell you
information that is important later without distracting you by that
information

A case in point is the information that

> 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

I'd like a bit snappier text, so it might be that we say

> The list of modules in the reactor is sorted in order to ensure that
modules are built before they are referenced by other other modules in the
reactor

Or better yet, maybe just

> The list of modules in the reactor is sorted

Where "sorted" is a link to a page describing the sort order.

But the most important thing from my point of view is to empower people
with correct information so that if they have a maven command such as

$ mvn clean javadoc:javadoc javadoc:aggregate-jar deploy site-deploy -pl
foo -am

Once they understand Maven, they can come back to the 60 second page and
see that it has not lied to them and that it actually hinted at how you
might go about understanding exactly what will go on with that execution

i.e. there is a build plan for that execution... there are lifecycle phases
and plugin goals... the aggregator goal affects the build plan in the
reactor, etc

But *and this is the important bit* the page itself does not have to
explain such a complex use of maven.


*aside*

One of the most annoying things to me about learning chemistry is that it
is a constant case of being thought something and then at the next level
they pull the rug out from under you and say, oh but actually it's not like
that at all...

They start telling you about electron shells

Then they say, oh but it's Bohr shells

Then they say, oh but it's QM

Then you dig deeper and there are layers to QM

By the time I got my degree in Chemistry I had gone through about 6 layers
of analogies for how the hydrogen atom works:

1st year-3rd year school analogy
4th year-6th year school analogy
1st year Chemistry analogy
2nd year Chemistry analogy
3rd year Chemistry analogy
4th year Chemistry analogy

Worst of all is that each analogy showed the previous ones as being
hopelessly wrong in so many ways.

Now I am fine with explaining things simply until you need to know more,
but when that simply way is just plain wrong!

Newtonian mechanics is at least a very good approximation of relativity for
normal velocities, and if I remember correctly, when the velocities are
small with respect to the speed of light the newtonian solutions are
trivially shown to be a simplified approximation of the general
relativistic model.

But you cannot say the same of QM and the lies I was fed in school...

To bring this back home, I want our top level tutorial to be viewable as a
simplification of what goes on *without* lying to you, i.e. like newtonian
mechanics vs general relativity not like 1st year school chemistry vs 4th
year university chemistry


On 3 January 2014 16:33, Stephen Connolly
<stephen.alan.connolly@gmail.com>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>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>:
>>>
>>>  On 3 January 2014 15:17, Robert Scholte <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>:
>>>>>
>>>>>
>>>>>  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>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
>>> For additional commands, e-mail: users-help@maven.apache.org
>>>
>>>
>>>
>>
>> --
>> Ron Wheeler
>> President
>> Artifact Software Inc
>> email: rwheeler@artifact-software.com
>> skype: ronaldmwheeler
>> phone: 866-970-2435, ext 102
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
>> For additional commands, e-mail: users-help@maven.apache.org
>>
>>
>

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