I’m still reading recently on a couple of blogs that Maven’s documentation is not very good. This is pretty hard to hear, because I rewrote a significant chunk of it at the end of last year 🙂
When I asked the question Why do you Hate Maven? last year, I got some good responses, it led to some changes, and I don’t think most of those arguments hold any more.
I’m hoping the same can happen with the Maven documentation. Do you think it isn’t very good? Is it a preconceived idea from before it was redone? Or is there something seriously wrong with it now? Hard to find information, incomplete, out of date? Is it the main site, or the plugins?
I’m the first to admit that we should have hit the ground running with Maven 2.0, but there has been a definite decision to focus on getting top quality docs together during the betas when all the features are stable. So if there are some lessons to be learned, now would be a great time to do it.
And if you’re going to say you are sick of square, red and grey – I’m with you. It’s time for a change 🙂
Brett Porter 
Hiya Brett,
firstly – I’m a huge maven fan, it’s the best thing since sliced bread.
I’d like to say it will be become the next defacto standard, but I’m afraid (sorry!) the documentation is a big down side. As with many technical projects, it’s not necessarily the best ones that get mindshare, it’s the best documented ones! (i.e. spring hibernate etc). (I’m not sure what the existence of jboss does to this argument).
The thing about documentation is that hard to find documentation has the same value as non-existent documentation.
I’ll give you a example of my lack of success with the docs.
I’m having trouble with reactor – each project has a build dir of build/maven. When I run my reactor project, I get an error message (failed, can’t find build/maven/ … )
Right – so it’s probably time I went and read the maven documentation so as to completely understand what is going on. I go to apache.maven.org, go to users guide -> using maven -> multiple projects
I find this section is really very brief – it does not provide comprehensive enough examples for the complete beginner to get going with.
Further browsing to the jelly tags and references also fails to give me more information.
Next (and absolutely the most important!) I google maven reactor – i get a hit:
http://maven.apache.org/reference/user-guide.html
The reactor documentation in here is ok – still not comprehensive and linking to an example for producing documentation – surely the most common usage would be building full applications, potentially j2ee (ears/wars/jars).
I also find with maven that plugin documentation is rarely on the verbose side. Normal practice with all maven users I know is to unjar the plugin and read the jelly script.
==
I guess in summary I feel the documentation is not really intuitive to find, and not yet comprehensive enough.
I acknowlege this may just be my simplicity.
Furthermore, I’m not criticising in a negative way, I already appreciate the efforts of the maven team in making such a great thing available. I’m just pointing out that to achieve the mindshare it deserves, the documentation has to be really, really good.
There are a lot of links on the left navbar, I find that confuses things for me when I’m trying to find something. Even more links if you consider that many of them are hidden behind a roll-up.
Reference-wise, I goto the project-descriptor reference the most. After that I’m going to be looking for reference on a particular plugins.
Plugin documentation is usually quite weak.
The various upcoming Maven books should help somewhat.
Looking at the Apache projects that have focused on getting good documentation, you’ll notice that documentation and site are always separate. Tomcat, Ant and Httpd all have a decoupled documentation concept and I think it works well.
I agree with Hugh and Henri’s comments. The sidebar links can be overwhelming and the Plugin documentation could be better. In general, the documentation is decent but can be hard to find.
What about reducing the sidebar to only show the categories? But don’t hide the Reference link since that seems to be the one I visit the most :).
The current content on the front page is pretty good. I would change the layout of the “Getting Started with Maven” subsection. The alternating bold-normal text makes it hard to read for me. Try something simplier, like making the questions themselves links. And maybe bump up the “Release Information” section. Preferably the front page should fit on a single screen without a scrollbar. It doesn’t for me with Firefox @ 1280×1024 resolution.
Anyway, good luck with it! I worked on the Avalon and then Excalibur site a lot and it’s always a work in progress.
The recent relaunch of the document on the Maven site was great. I think that the documentation is really coming along, and some of the things you’ve done over the past two months are really help to make the documentation accessible and easier to navigate.
The only recommendation I have is to move the front-page of the maven.apache.org to a 3 column format. Keep the left-hand column strictly business – “Getting_Maven”, “Getting_Started”, “About_Maven”, “Users_Guide”, “Getting_PLugins”, “Maven_Subprojects”. Move information about the community and related projects to a right-hand column…so, “News_and_Resources”
….but Brett please know that your doc changes are great.
We’re just starting to look at migrating to Maven for a project at work. We have two apps, both use a number of common libraries from other places (log4j, etc.), and the one project imports portions of the other project as a library. Sounds like a job for Maven.
I’m finding the Maven 2.0 documentation at the Apache site difficult to grok. I think it is because there are a lot of assumptions and expectations that are left unsaid. A few too many references to Maven 1.0 – I’m starting fresh with 2.0, I don’t want to learn the deprecated version just so I can understand the new version.
The documentation seems to assume you are deploying your product as a monolithic archive (jar, war). We’re not doing that, we’re making some .jars, but there are .properties files, and other resources, too.
It suffers from the same problem much technical documentation does: It it explains the what, but not the why.
I’m still fairly early on the learning curve, but so far it looks like the Maven 2.0 documentation is geared towards folks already well versed in the “Maven Way”. This is probably just an artifact of it being in the early stages of supplanting 1.0, but it does confuse me as a complete newcomer.
Here’s an example of a wall I’ve hit in the documentation. We are using Java 1.5 as our target. I worked through the Maven docs to set up an archetype project, moved some source code around to be in the right place, ran “m2 compile”. Wham! An error pops up complaining “generics are not supported in -source 1.3”. I didn’t set my source to 1.3. Hunt around in documentation, finally find that there are parameters for the goals. How do I set the parameters? I have no idea. MAYBE that info is hiding in the 1.0 docs somewhere. But again, a case where the 2.0 docs assume intimate knowledge of 1.0. For now, I may as well skip 2.0, learn 1.0 and then transition to 2.0 once I’m intimately familiar with 1.0 and its quirks.
It’s looking to me like 2.0 is still too early in the development & documentation process to be used by newbies.
Please bare with me, I may sound critical, but I don’t mean to be. The fact that you have asked the question is a good start, but your comment about your disappointment indicates that you may need to write, or find someone(s) to help you write a whole lot more doco, before its up to the task.
First I would ask you to look at the Ant manual. There are examples for almost everything. When I look something up, I can generally find it, and I can usually find several examples, so that when I construct a specific instance of “X” in a build.xml file, I’m pretty confident that it will work. Now look for examples of using the maven:reactor tag at the Maven site. I cannot begin to tell you how many people who really want to learn to use Maven have told me that they couldn’t figure out how to get the reactor tag to “reliably” do what they wanted, so they had to bag the whole thing.
Maven is not a “build tool” like Ant. With Ant each build.xml file is unique and must be written from scratch (though Javagen JAM does help resolve some of that) Maven is a “development platform” 😉 As I’m sure you are aware, Maven’s solutions to project modeling, artifact management, project directory layout, project build lifecycle, project site generation and to a “write once, run many” approach to project development/maintenance are head and shoulders above Ant’s. I have any number of projects that don’t require a maven.xml file at all. Why wouldn’t anybody who knows their stuff want to use it?
Ah, but there’s the rub. With Ant the simple things are hard, but the hard things are doable. Maven represents the converse, the simple things are dead simple, and the hard things are impossible, at least for the novices and for people attempting to “cross the chasm”. So, what are some solutions?
I think that a “Maven Cookbook” would go a long way toward easing people’s pain. Rather than forcing people to read the plugin.jelly files of all of the plugins, the doco folks ought to select good examples and put them up on the “Maven examples” pages. Besides, how many times do I have to read someone talk about extracting plugin contents to read the jelly files before one of you guys explicitly writes, “All plugins are extracted to the Maven cache directory, no need to do it by hand.” Issues concerning plugin writing practice ought to be addressed. I think that the nasty issues concerning the need for both a test and an itest plugin ought to be addressed in a public manner. Shouldn’t there be a way to create a single plugin that could handle both functions? And yes, I know that the Surefire plugin will be released with M2, but will it solve both problems?
Maven is a great tool, but it won’t be able to capture its rightful audience unless and until someone(s) do the grunt work required to significantly lower the cost of entry.
I think that pages like this can serve as a case study of why the documentation still needs some work:
http://maven.apache.org/guides/introduction/introduction-to-the-pom.html
Well, I am a complete beginner to Maven. Moreover, I have restricted access to Internet. I wanted to download the whole documentation and take it offline to my home PC and read at my leisure. But unfortunately I could not find any link on to do so on the entire Maven site. Moreover the binary zip that we download contains absolutely no documentation whatsoever. This is contrary to other frameworks like Ant, Struts, Spring, Hibernate! I get all the documentation bundled with the software itself, and if I want to download JUST the documentation, I can do so separately. Struts infact comes with a complete offline version of the whole apache site…something really nice to have. That’s why I found the documentation to be bit difficult to access.
Hi,
I am also trying to start with Maven 2 and it is REALLY HARD.
I don’t want to write a plugin (maybe later)! I just want to use it, i.e.
– checkout some source code from CVS/SVN
– compile it
– package it in a jar
Only for the last two task I could find a “getting started” info. How to checkout code is nowhere…
:))))))))
The whole concept of Maven is broken. It does too many things ‘automagically’. When it works – great! When it doesn’t do what you want it to do (which is most of the time), you’re completely screwed. There is no traceability with this 4GL style of implicit scripting. Just like springs dumb-ass concept of IOC, you’re left staring at the screen wondering how and why on earth things are happening and how in hell you’re going to debug and fix them. Maven was not designed to be ‘human’ friendly. If you’re going to write this kind of tool, you should give it a decent user interface. Maven seems to only have two levels of logging, practically nothing and WAY TOO MUCH. With this kind of tool, you need masses and masses of documentation, since using it is COMPLETELY UNINTUITIVE. I don’t expect the bozos that developed the idea have any appreciation for good documentation or they wouldn’t have designed it that way in the first place. It’s useless and is the bane of my engineering life these days. Nobody here knows how to use it and the twit who made it his mission to enforce it upon us has jumped ship to his next contract.
Well, listen, Mr. Anonymous, first off, Maven’s document did suck a few months ago, but if you think it sucks now, you haven’t been paying attention. And, please get some manners, telling Brett that Maven’s documentation sucks hits close to home, Brett has spent a lot of his time rying to fix the problem.
But, that’s only the beginning:
A. Yeah. Maven sucks like Spring sucks, maybe that’s why everyone’s adopting them both, because they are both such terrible technologies.
B. Documentation, I’m going to take a guess here, you are the kind of developer that doesn’t really care to read much. Because if you took half a second to do some research, you’d quickly realize that there is a FREE BOOK provided by Mergere. That book doesn’t just touch upon simple topics like setting up WAR/EAR projects, it gets into the details.
C. Maven does too much ‘automagically’. Yeah, man, that sucks, I hate the fact that it just knows how to compile Java classes and run unit tests, and I long for the dys when I had to do all that stuff manually in some Ant build. Who are you? Seriously, Anonymous, identify yourself.
D. As for it being COMPLETELY UNINTUITIVE – it isn’t like there are about a thousand open source projects out there doing everything imaginable with this tool. It isn’t like you can’t go search a million blogs for “How do I get Maven to build X?” And, it isn’t like everyone I speak to isn’t constantly asking for my help to move to Maven 2. Again, the industry proves you wrong, but i’m not surprised, there are still people using Struts 1.x and convinced that they are the smartest people alive.
E. “Nobody here knows how to use it and the twit who made it his mission to enforce it upon us has jumped ship to his next contract.” I’m going to go out on a limb here, but I’m pretty sure that this “twit” probably left because of you. You definitely don’t sound like the kind of developer that people enjoy working with.
Seriously, Maven succeeds often, and the only way I’ve seen it fail is when really misguided architect prima donnas start defending some complex disaster that they’ve invested ego into. Have fun. Oh, and troll away, I welcome the fight.
Do you have any documentation on strategies to migrate a maven 1.x build to a maven 2 build?
Our current build process invokes several jelly scripts. The original designer of these fabulous jelly scripts has moved on to an opensource company and none of the current developers have the time or energy to
a) learn jelly
b) figure out what these umpteen jelly scripts are doing.
c) write a maven 2.0 plugin to replace their behavior.
We prefer to bitch and whine about our lot in life. 🙂
Picking up Maven2 for first time. My problem stems from a previously established project directory structure in Subversion, accessed by the Tortoise IDE (cool by the way). Getting the project into Eclipse 3.2 is simple enough. But now I’m needing to employ Maven for builds. It’s project structure requirement is in conflict (it seems) with the established project in SVN/Eclipse. What is the best strategy/procedure to employ to get Maven to play with Eclipse and the pre-established project structure? The free book already mentioned here doesn’t cover this scenerio. If it does then apologies for missing it. Point me, please.