April 29, 2009

Maven Documentation: The Missing List

A rather weak talent of Maven is probably its documentation. This is my personal opinion, but it seem to match what other people think. Yeah, it has been gotten better, but there is still some room...

It's not that there is not enough documentation available, it's just that the existing documentation is poorly organized and you often can't find what you need. Moreover, many documents (especially for plugins) are only scratching the surface, not even diving into the important shallows. Or, even worse, they give you wrong or inconsistent information...

Here is just one example: The surefire plugin page for surefire:test goal gives this description for the excludes parameter: "List of patterns (separated by commas) used to specify the tests that should be excluded in testing. (...)". However, the example page for "Inclusions and Exclusions of Tests" shows an example that uses nested elements – wait, what about the commas? So, what do you do? Go ahead and try yourself? I bet this type of annoyance is hitting every Maven newbie sooner or later.

Well, maybe the Maven team should start a coordinated, collaborative effort to improve documentation just like Wikipedia is doing once in a while. Or, better yet, why not move all documentation into some open Wiki and let the community work on what it thinks is missing, broken, inconsistent, badly organized, ...

Well, until then, we have to use what is available. This post tries to list most important pieces of online documentation, indispensable when you are dealing with Maven in a professional way. Let me know if you think something is missing on this list...

Introductory & General

Books

  • Maven: The Definitive Guide – a free book by Sonatype (using a Creative Commons license). High quality, up-to-date, written by some of the famous Maven gurus: Tim O'Brien, John Casey, Brian Fox, Bruce Snyder and Jason Van Zyl.
  • Better Builds with Maven – another free book, originally maintained by Mergere, now managed by MaestroDev. This, too, is written by core members of the Apache Maven Project: Vincent Massol, Jason van Zyl, Brett Porter, et al.

Technical Details

Community

Other Useful Links


Updates

  • 2009/05/11: added link to Sonatype's "Summary of Maven How-Tos" blog post – definitely worth to be listed here...
  • 2009/05/28: added link to Maven Properties Guide wiki page

2 comments:

  1. I agree, that's why I've dedicated a good portion of my time to the Definitive Guide over the past few years.

    If you have any specific requests, we've recently opened up the book effort. If you are missing something specific, file a bug here: https://issues.sonatype.org/

    Thanks

    ReplyDelete
  2. Tim, I really appreciate the effort you and others have spent working on this great book. It's definitely one of the best pieces of Maven documentation available today, and even more: it's free and online.

    However, when really diving into Maven builds, I usually need more in-depth information: 1) Maven reference documentation (on POM schema, lifecycle phases/bindings etc.) that is succinct, correct and available "at your fingertips" without having to search in books; and 2) information on all those plugins and their goals & options, hosted by Maven team, codehaus or others. While 1) usually is available (you just have to find it), the quality of plugin documentation is rather, well, varying -- and more often than not just insufficient, IMHO.

    I would love to help improve that if it were easier to participate. Checking out a plugin, edit its site files and posting a patch to the issue tracking or mailing list is just too tedious. A wiki could help, but of course I'm aware that it may have disadvantages, too (like loosing connection between plugin's sources and documentation, which is a big advantage of Maven sites).

    Anyways, I'll try to participate and file my thoughts/corrections for the book... thanks for the Jira link.

    ReplyDelete