maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Barrie Treloar <baerr...@gmail.com>
Subject Re: Complex Maven projects - Tutorials? Books?
Date Sat, 14 Jun 2014 02:26:13 GMT
On 14 June 2014 02:14, Robert Kuropkat <rkuropkat@t-sciences.com> 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 <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.
>
>
Sometimes the people implementing things can't see things from a fresh
perspective - they can't unlearn what they already know.

That is why we rely on the community to provide patches - even to
documentation - to help clarify things.
It's a great place to start if you want to get involved - it's where I
started.

We also need people withe skills and desire to improve documentation.
Technical writing and cutting code are orthogonal skills that rarely sit in
one individual.
So if you have someone on your team who can write technical docs then
convince them, your management, etc that it benefits your team to help
improve these docs and give back to the project. It will also help future
projects at your org.

Actually having access to OLD documentation would help understand the
> difference between the "old but still supported" vs. the "shiny, new
> preferred" way.


The previous plugin docs are always available they are versioned on the
website.
But they are unlikely to discuss why things were changed.
You might get lucky and find that information in the jira changeset.


> 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.
>
>
That discussion is in the mail archives, but you would have to hunt for it.
If you are using maven 3 then the reporting section no longer works.


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

You've described my job too.
I tend to write things up not for others but for myself in the future.
I've been surprised more than once to google a problem only to find that I
answered that myself a while ago...

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