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 <mpd...@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-unsubscr...@maven.apache.org
For additional commands, e-mail: users-h...@maven.apache.org
