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?

Project Management (….and Reporting)

Maven’s promise is two-fold: it will help you manage (read build) your project and it will help you understand your project. Depending on who you talk to, Maven is a “project management tool”, a “project management and comprehension tool”, a “total project life-cycle management tool”. All of this has always sounded forced to me, and, in my opinion, the lofty talk of “project management” tends to confuse the issue. 95% of the time, people are looking for a build tool…that’s it. Reporting and site generation are nice extras, but the developers I work with every day see it as a secondary concern. So, I’m going to tell you what I think Maven is, and it isn’t the orthodox line: Maven is a build tool. Forget, “Maven is a project management system that allows you to cook, clean, and effectively leverage your synergies”. It’s a build tool, and if you really want to use it generate a site, go straight ahead, but, be warned, the sites it creates are pretty poor looking and customizing the presentation consists of applying CSS styles to poorly crafted mark up. So, move your project to Maven 2 for the build system, the dependency management, the array of plugins, but beware of the Maven site plugin, it generates ugly websites, and IMO it typecasts your project as “yet another maven project”.

Customizing Project Info Reports

Take a look at most Maven 2 projects, and you’ll see the well-known Project Info reports. They are: “Team List”, “Project License”, “Issue Tracking”, “Project Dependencies”, and “Source Repository”. The general idea behind these reports is that projects that use these out of the box reports don’t have to write boiler plate text like the following on the “Team List” page:

Figure 1. Maven’s Team List comes with these paragraphs out of the box.

At first glance, this seems to be a great benefit, you didn’t have to write any of that, Maven just creates a page that took your project’s pom.xml developer and contributor information and created a web page. I’ll bet it isn’t even something you’ve bothered to read, it’s boiler plate text, “here are the committers and contributors, committers have access to the repository, while….” ….. snooze ….. Who wants to write that kind of stuff anyway?
It’s time consuming and a little boring. Plus, you’ve got a thousand other things to do, why not just assimilate your project’s site with the approach that Maven encourages. I was the one who wrote the “Resistance is Futile” note in the Maven Developer’s Notebook, and the analogy is perfect. Everytime you read that text, imagine a Borg voice speaking it.

The Problem: Meaning Decays with Repetition

All communities are different; instead of differentiating your own development team and providing some personality for your project, you’ve just relied on a robot to set the tone. A robot effectively wrote, “The number of Contributors to the project is unbounded. Get involved today.” That is clearly a passionate robot, and I’m sure you share the sentiment, but I’ve seen that paragraph so many times it doesn’t mean anything. It is open-source robo-cheerleading; at first, it probably meant something to someone, but now it reads like an ironic Radiohead song or a form letter from the IRS. It isn’t project management and reporting as much as it is “project management and reporting auto-pilot for the busy”. Go focus on code while Maven gives you license to neglect project documentation.

Your project’s web site is important, it is a central piece of the community you are creating, and this form letter approach to project documentation is no better than just relying on the default sourceforge project page. Here’s a helpful rule I’ve stumbled upon in documentation: if it isn’t worth having a human write it, it isn’t worth having a human read it. I think this rule applies to the bulk of Maven’s auto-generated reports. Google “successful project requires many people” and you’ll see that a large population of Maven sites all have the same community dynamics:

Figure 2. 18,000 Maven projects in the wild?

18,000 maven projects? I not sure about that metric, but 1000 sounds like a better number. Searching for that exact phrase and showing all omitted results displays 100 pages of results for about 1000 matching pages. Maybe Google only shows the first thousand of an exact phrase match, but the point here is that while Maven is widely adopted, every project now has this boiler plate web page that just repeats the Holy Litany of Maven. “We believe in One Maven, project management tool and Creator of All…”

It was better when it was worse… :-(

Maven settled the site generation battles that Jakarta was having long ago in ‘02. Some people were using Forrest and some people were using Anakia, then Maven came along and “simplified” everything. I drank that juice and helped move Commons toward Maven 1; in hindsight, I think we’ve just shuffled a mess around. Documentation is just as neglected as it was before, but now it is buried in a Maven site that emphasizes developer-centric project reporting over user-focused simplicity. All Maven sites tend to look a little boring, even the one’s with customized stylesheets still have odd navigation and cookie-cutter reports. When I look at really appealing sites like Mozilla, I wish site generation wasn’t as tightly coupled as it is with project builds. It’s contrarian, but I see the power of disaggregating a project’s build from a project’s site.

Customizing the Team List

What happens when you want to use Maven in a project that doesn’t have a developer/contributor separation? What if you don’t want to have that paragraph show up? Even though Maven has a default mailing list info report, what if you rely on Google Groups and you don’t have a subscribe or unsubscribe email address? What if you want to customize the column on the Team list page? etc. In other words, how do you customize the project info reports?

Let’s dig into it. Let’s try to figure out how we could change that default paragraph to something more human.

Step One “Mini-guide”:

First stop is the Guide to Creating a Site mini-guide. It is a start, but it doesn’t mention customization of the default info reports. There is a section that tells us how to add these reports to the site, and it instructs the reader to add maven-project-info-reports-plugin to a special reporting plugins section of the POM.xml. OK, so we’ve established how to add them to the site, but no information about changing that boiler plate text. The mini-guide does end with a pointer to the Project Info Reports plugin documentation. Let’s check that out.

Step Two “Plugin Documentation”:

Maven is really just an execution framework for various plugins. Plugins do all the work and heavy lifting, so 9 times out of 10 when you need documentation, you’ll be looking at plug-in documentation. Now that I’m looking at the “Project Info Reports” Plugin home page, I’m noticing something odd. Nothing on this page provides context, the site has the default logo and banner - “Apache Maven”. click, see for yourself. There isn’t any page title or context, I’m looking at a default site. Irony alert: I’m trying to figure out how to make my site look more appealing. in the process of doing so, I’m confronted by a report plugin site that doesn’t provide any context or title. The only link back to where I came from links back to the top-most Maven 2 site. In the age of blinken AJAX lights, there is no slick tree widget letting me navigate through the plug-in docs.

This plugin provides two documents “Introduction” and “How To Use”. Neither of them answer my question, how do I change that boilerplate text. they do tell me how to run all of them or run only a selective few of them. (The fact that the Project Info Report Plugin site has the Project Info Reports is just mocking me.) NOTE: This is the point where most users give up.

Step Three: “Google” and “Nabble”

Getting a little more frustrated with this, and not yet willing to look at the code, you decide it is time to Google this problem or better yet seach the mailing lists over at Nabble.

• ” I like to not show the email address of contributors and
  developers, and fold some of the columns. How can I provide that
  functionality?” - on the user list from December. No answer.
• User with a question centered around the project info reports and the lack of documentation - is redirected to the existing Maven documentation. Dead end.

I continue looking for a while and then give up. If anything, since I helped write a book about this product, isn’t it partly my responsibility to take a crack at it and write the documentation? Sure, but I’m not using Maven for Maven’s sake, I’ve got a job to complete. I’ve already spent too much time finding dead ends.

Step Four: Go to the Source

Going back to “Project Info Reports Plugin” site, I click on “Project Info” in the left nav column, and then I select the “Source Repository” report. On this report, there is a link to a Subversion repository, and, much to my surprise, it links to an invalid path. ViewCVS prints an unknown exception. More Irony: I was trying to use a Project Info Report on the Project Info Report Plugin’s Site, and it points to a dead-end. Taking two steps back, I then notice that there is a section in the Left Nav called “Sample Reports” that also has a link named “Source Repository”. I click on that link instead of the one int eh Project Info submenu, and I get another URL. That link is also broken. Ridiculous!

I then look at the URL, and shave off everything but this http://svn.apache.org/viewcvs.cgi/maven/. Now, I’m looking at the root of the Maven project’s SVN tree. I happen to also “just know” that the project-info-plugin is here http://svn.apache.org/viewcvs.cgi/maven/plugins/trunk/maven-project-info-reports-plugin/. Underneath this directory, I find the following file: src/main/resources/project-info-report.properties. This is the source of the boilerplate text. Evidently the project-info-report plugin reads all of the messages it displays on this report from this properties file. That file is accompanied by other files that convey the same universal robot message in Simplified Chinese, Polish, French, Portugeuse, and German.

Step Five: Losing All Hope

If you look in src/main/java/org/apache/maven/report/projectinfo you’ll see that each Report is captured in a Java class. When Maven 1 was rewritten, there was an effort to rewrite every plugin in Java. Evidently someone took the universal edict that all plugin’s need to be written in Java a bit too seriously. Take, for example, the code that renders the team list table in TeamListReport.java:

Here’s some code that prints out JavaScript from Java:

  // To handle JS
  StringBuffer javascript = new StringBuffer( "function offsetDate(id, offset) {n" )
      .append( "    var now = new Date();n" )
      .append( "    var nowTime = now.getTime();n" )
      .append( "    var localOffset = now.getTimezoneOffset();n" );
  // more omitted for your benefit...

And, some more tibdits that render tables….

  sink.tableRow();
  tableCell( contributor.getName() );
  tableCell( createLinkPatternedText(contributor.getEmail(), contributor.getEmail() ) );
  tableCell( createLinkPatternedText( contributor.getUrl(), contributor.getUrl() ) );
  // And more, click on that link and see for yourself...
  //    we've got JavaScript and HTML being appended to
  //    a StringBuffer.  Yikes.

So, Java is the templating language for this plugin, I guess because it’s faster. What is going on? I’ve just given up on customization. I thought I’d be able to just drop a Velocity template under src/site somewhere, and I’d be done. But, in the process of getting to the bottom of the problem. I’ve just lost faith in the entire plugin.

Step Six: Open Ridicule

Step Six? You are reading it.

Four Conclusions

• Avoid the Default Reports - Instead of relying on Maven to spit out tens of generated pages with information about source control and team list. Consider writing these pages yourself or writing your own project reporting plugins. do us a favor, if you right some good configurable report plugins, share them with us. Many in Mavenland would disagree, but I think the Maven default reports are harmful the character of your community.
• It should be illegal to not customize the Maven stylesheet. Enough said. Publishing a default Maven stylesheet is criminal negligence, follow the lead of projects like Jetty or Display Tag for ideas on customization.
• Maven Suffers a Great Documentation Gap - Once you’ve decided to customize behavior through plug-ins, you’ll quickly come to realize that much of Maven is uncharted territory. The mmini-guides are helpful, but they get you only so far. You are certain that a particular option, property, or descriptor exists for a plug-in, but there is no easily accessible documentation or you’ll encounter the dreaded “To Be Finished” text in some documentation. Because of this lack of documentation you will have to resort to one of two options:
  • Follow the Leader - Figure out how to configure Maven 2 by looking at the pom.xml of a project that does what you want to do.
  • Look at the Source - Checkout the source for Maven and/or a Maven plugin and figure out how the plugin in question reads particular configuration points.
• Maven plugin documentation is not cohesive or unified - it is scattered throughout Mavenland, and isn’t presented in a way that makes it easy to locate information. Various plugins can define various descriptors and there is a variety of approaches to presenting tutorials and how-tos.

IMO, the only way to effectively use Maven is to grok the source code for a plugin or wait until someone else has done what you’ve done.

How to fix this?

The Maven project hasn’t committed itself to writing documentation as a co-equal concern to writing code. By this I mean that documentation of a project isn’t on par with the development of a project. If you are going to try to change the way people work, you should at least provide as much detail as is possible. Even with incresed focus, Maven’s documentation is limited and shallow; if you start diving into the syntax of a particular descriptor, you’ll quickly realize that the only real documentation that exists is the code itself.

Concrete Solutions

IMO, and no I’m not proposing this nor do I have a poersonal stake in the following….

• Define (strict) Plugin Documentation Formats and Requirements - While I’m against the standardization of project sites, I’m 100% for the standardization of plugin documentation. Plugin sites should all look the same and then should provide similar hooks. Information about plugins should be published as both pages and snippets of content that can be aggregated into an AJAXian documentation tool.
• Write a Reference Book -
  Maven needs less of a general book “Maven: Overview”, and more of a “Maven In a Nutshell” title. It needs a reference, but to do this the plugins need full, detailed documentation. Maven needs less of a narrative “Let me guide you through the wonderful land of Maven” book, and more of a “Here’s what the site descriptor looks like”, “Here’s a table that lists every possible element and what the possible attributes are”.
• Pay a Programmer To Write -
  There are already numerous people paid to work on Maven full-time. The company behind this effort should pay a developer just as much money as they pay current developers to write technical documentation - full-time. Developers are terrible writers, but only developers can write good technical documentation for a product aimed at developers. It is a tough paradox to deal with.
• Documentation is a Release Veto -
  No releases should be made until a particular release tag can pass the novice test. Not just for the simplest of use cases but for a few of the more complex ones as well. Even if this means that nothing is released for months. That project should also consider cutting back on features - no feature enters a plug-in unless it is documented to completion. This isn’t true for every project in the world, but for a project that aims to be the foundation of everyday development, this is essential.

I expect…

…someone from Mavenland to tell me that there’s some piece of information I’m missing, or that if I had just asked on the user list, I would have been able to figure out how to do this. …that’s ignoring the fact that this small issue is more of a symptom of the larger problem. Listen Maven’s core features are good, I find that it builds reliability, but I think it has taken on much more than it can chew, and I’m not convinced that it is a good choice for site generation.