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
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
- Main Site for Apache Maven project
- Maven Getting Started Guide – intended as a reference for those working with Maven for the first time
- The Maven 2 tutorial – a practical guide for Maven 2 users from Codehaus
- offical FAQ and unofficial FAQ
- Sonatype's Summary of Maven How-Tos
- List of Web Tutorials (How-To's)
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
- Maven plugins
- Maven Plugins – lists the core plugins (supported by the Maven projects) and others
- Mojo Project Plugins – hosted at Codehaus repository
- Cargo Maven Plugin – used to start/stop J2EE containers and deploy to them
- Docbkx Maven Plugin – hard to find, but useful for generating HTML/PDF from DocBook
- The POM
- Other important references
- Directory Structure – description of the standard directory layout
- Build Lifecycle – lifecycle basiscs and bindings
- Maven Properties – a list of properties available in Maven 2
Community
- Maven User List, hosted at MarkMail
- Maven Developer List, hosted at MarkMail
- Maven Project Issue Tracking (Jira)
Other Useful Links
- Maven Central – official Maven 2 repository
- MavenSearch.net – search several Maven repositories
- Jarvana search engine (Beta) – Maven-focused Java class and archive search engine
- Maven POM Report – verify if the dependencies in your POM are up-to-date
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
I agree, that's why I've dedicated a good portion of my time to the Definitive Guide over the past few years.
ReplyDeleteIf 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
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.
ReplyDeleteHowever, 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.