Maven Project Info Reports Considered Dangerous

by Tim O'Brien

Related link: http://maven.apache.org




Note: Remember I like Maven. I recommend Maven, now read the following harsh criticism....




Maven is touted as the project management tool to end all project manangement tools. I wrote as much in the Preface of Maven: A Developer's Notebook, and while I think that Maven offers some great tools in the way of project builds and dependency management, the continued lack of project documentation is a constant obstacle to adoption. Take, for example, the problem that confronted me this last week. I was trying to customize the site that Maven generates because I was frustrated with the cookie-cutter text and boring Maven stylesheet. I had assumed that customizing a Maven Project Info report would be straightforward, but on my way to a solution I found a great gap in communication and documentation...I've decided that the best medicine for Maven is overly harsh criticism. :-) Read on...





All your base are belong to Maven?


7 Comments

pansapien
2006-03-04 01:33:28
Here, here!
I can't tell you how many times I've tried to do something with Maven 2 in the past few months only to be unable to find any useful documentation.


It's unfortunate as it's much nicer to work with than Ant once you guess at the needed configuration.

NiteOwl
2006-03-04 06:02:25
j2ee, jboss and to dash against the rock
I like the Maven or I would say the Maven idea.
Now I just want to use it.
What we have is a typical jboss j2ee application
The directory structure is following:
ear->[sar,...],war,ejb
What I want :
1. to compile and deploy
2. But I want to keep a link from my development war directory to jboss/deploy directory instead of copying and packaging war during deployment to the development server. Because the structure of war in my project directory is absolutely the same as a typical war archive.
We can then easily modify jsp, resources and so on , press refresh in your browser and see results.
3. With the production mode the full project should be compiled and deployed of course.


Please, give me a chance to love Maven practically but not just theoretically.


Does anyone uses Maven 2.0 for deploying j2ee projects with the same tricks ?



tmo9d
2006-03-04 08:33:47
j2ee, jboss and to dash against the rock
NiteOwl, can't provide any good insight into your JBoss issue. but, I can tell you tat I develop web application in place with an Eclipse Tomcat plugin - but that probably doesn't help you very much. :-(


But, you did supply me with two great quotes that I think sum up our situation (which I'll clean up):


"I like Maven or should I say 'The Maven Idea'"


and


"Please, give me a chance to love Maven practically but not just theoretically"


I think we all know that Maven is headed in the right direction, but it is the details that tend to get in our way.


Tim

Julian Wood
2006-03-14 18:14:49
You may be interested to know that there is some strong movement to correct some of your concerns. The move would be that code cannot be committed (ie the builds for maven itself will fail) if there is insufficient test coverage and insufficient documentation. Read Brett Porter's recent note (Brett is one of the lead developers).


http://mail-archives.apache.org/mod_mbox/maven-dev/200603.mbox/%3c440DE8CD.4010402@apache.org%3e


This probably won't solve the problem entirely, though it will go some ways to making sure if something is published, it will at least work as advertised.

Tim O'Brien
2006-03-17 07:33:12
Julian, if you read that thread, you'll notice that John Casey and I have a pretty long exchange in there about document vs. the Maven site. I'm supportive of the efforts with the Maven project to address the lack of good documentation, but I'm more convinced that Maven needs a solid external documentation effort.
epere4
2006-05-31 21:52:28
Wow! I can't agree more with you, Tim.
I was following your very same steps until I find your article!
Please note the link in "Source Repository" report section from the "Project Info Reports Plugin" site is now working. They must have fixed that.
David Main
2006-06-07 07:27:22
Hum... epere4, I'm not sure things have been fixed. I just tried both links this morning and they are both broken. The irony is that I am interested in writing a plugin that rides on the reporting infrastructure in Maven and was struggling to find any documentation. Just as Tim thought, I decided to go to the source... but none of the links work!


I am starting to have a love/hate relationship with Maven. One the one hand, it has jump-started my career into Java webapps so thoroughly that I can't imagine working without it (in fact, I truly wouldn't know what to do without it). On the other hand, every time I want to do something new, it ends up taking a lot of time because I have to follow the "follow the leader" and "look at the source" (which in many cases really means, "decipher the code").


I suspect this situation is really very normal for things created by humans. We all know what we *should* do (i.e., write useful documentation) and many of us know what good designs are. The rest of us follow the leader, get the job done and move on... leaving the things we know we should have done un-done till another day.


In any case, Tim, thanks for your rant. It's a good one and hopefully Maven folks will take it to heart. But you also provided some very useful information... I'm probably on my way now thanks to your blog. Muchas gracias.