maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Kuropkat <rkurop...@t-sciences.com>
Subject Re: Complex Maven projects - Tutorials? Books?
Date Fri, 13 Jun 2014 16:44:50 GMT

On 06/13/2014 10:27 AM, Mark H. Wood wrote:
> On Fri, Jun 13, 2014 at 09:23:31AM +0930, Barrie Treloar wrote:
>> On 13 June 2014 09:07, mike digioia <mpd395@gmail.com> wrote:
>>
>>> So how does this book help you any more than all the detailed online Maven
>>> docs that exists and are updated?
>>
>> It's just another source of information.
>>
>> The docs don't really walk you through everything, they are mostly focused
>> on a particular plugin and not on how to pull all this together.
> Indeed.  One thing I really miss from the evil old mainframe days is
> the manuals that gave you the big picture and the developers' view of
> how they expected the tools to be used.  There were usually two books
> for any product:
>
> o  Reference Manual -- *complete* individual descriptions of each feature,
>     command, and qualifier.
>
> o  Programmer's (or User's) Guide -- fits all the pieces together and
>     suggests good ways to think about the facility under discussion.
>
> I typically had both open when working on anything nontrivial.  It's
> essential to have both the macro and the micro view of a tool, to use
> it well.
>

I'll add my cry of despair here as well.  Modern Open Source 
documentation efforts tend be mostly disappointing.  First of all, it's 
never in a nice neat collection.  Second, most of the articles and 
examples supplied by Senior Mentor Google are stale, trivial and 
sparsely explained.  Explanations are rarely more than a statement of 
the obvious (Property: enabled:  true/false - enable or disable 
feature).  The question of WHY is rarely addressed and downstream 
results never.  Even if you do find a well detailed example it is very 
specific (cookbook style) with little explanation of the options NOT 
chosen and why.

I'm running into this right now in fact.  I did some proof of concept 
testing on a bunch of plugins for my group, things looked good and now 
I'm reviewing my configurations and documenting them. I've managed to 
run across a few issues where configurations I plucked off the Internet 
are "working" but don't seem to be valid. At least I can not find any 
documentation for the options I set.  Is it stale documentation?  
Deprecated options?  Just plain wrong examples?  With a configuration 
file like XML which is designed to ignore options it doesn't understand, 
this is even more frustrating.  With rapidly  changing feature sets it's 
maddening.

Actually having access to OLD documentation would help understand the 
difference between the "old but still supported" vs. the "shiny, new 
preferred" way.  I still have not found a good discussion about the 
difference between using the POM reporting section and adding reporting 
plugins to the maven-site-plugin in the build section. All I know at the 
moment is more plugins seemed to work as I expected when adding the 
plugins to the maven-site-plugin in the build section than when trying 
to add them to the reporting section.

For whatever reason, my career has been one of trouble shooting, proof 
of concept and other, very targeted activities.  I almost never do the 
same job or use the same technologies for more than a year or two.  My 
efforts historically rely on being clever, persistent and willing to buy 
every book I can find on the subject. Generally, the modern JavaDoc 
mentality of documentation blows.  If I want to read the source code 
(and I can) I'll write the source code (which I can).  If I have to dig 
in that deep to figure your plugin out, it's not really saving me much 
time is it?

Robert Kuropkat



---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org


Mime
View raw message