+1
Ron
On 13/06/2014 12:44 PM, Robert Kuropkat wrote:
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 <[email protected]> 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: [email protected]
For additional commands, e-mail: [email protected]
--
Ron Wheeler
President
Artifact Software Inc
email: [email protected]
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
