I’ve had it with Maven sites and xdoc!

Ah, Maven. Everyone who has ever met me in real life and talked to me about Maven, knows my love-hate relationship to this tool. Maven, just like Microsoft Windows, is deceptively easy to use. It is sometimes even shiny. It does things where you have to write lots of ant-script-lines in a few lines.

But if you scratch the surface and try to adjust maven to do what you want and it is not exactly the Maven way of doing things, you will find out that Maven is very good at breaking in exactly the wrong moment. Not because Maven is a bad tool. Not even because it was written with a mindset of forcing a personal Weltsicht on unsuspecting tool users. But because it was written partly in a language that frankly sucks at being usable for any real world work.

But I wanted to rant about Maven sites. Not Maven itself. Well, Maven sites. They look great. They are easy set up and contain all that meta-information that one wants to know about a project and it would talk a lot of ant wrangling to get all this informations in a whim:

• Javadocs
• File Activity, Developer Activity and SCM change log reports
• Code metrics
• Automated crud checkers such as PMD, Checkstyle and Findbugs

and the list goes on and on. But here comes the catch: Most of this information is volatile. It simply does no longer work if you want to go back in time and want to rebuild a site in a defined state.

This might stem from a philosophical point of view that some of the developers have. If you followed the Maven development (as I did because it somehow mushroomed out of the Turbine project) as closely as I have for a while, you might have noticed that up to 1.0 (or with the current 2.0 branch) the most important bit of advice from the developers was: Use the most current trunk version. The reluctancy to actually RELEASE a version, call it 1.0, 1.0.1, or 1.1 but to insist on working with unreleased SCM snapshots is like a red thread going all through maven development.

And here, the current maven site concept shines! Rebuilding the site from a trunk every few hours/days is perfect. You always have up-to-date information.

But it does not help you much. Because for a release you want to lock information in a state as it was when that release was made. Releases are about repeatability. About stability. And guess what: If you download a (maven-build) dist-src package, and rebuild the site, it no longer matches. And it doesn’t match in the most crucial parts: The changelog, File and Developer activity parts. So if you didn’t built a site at release time, then this information is all gone. You can never go back again!

And then documentation itself. Maven has this great concept of including xdocs. What are xdocs? They are documentation in a souped-up XML format which comes from the Anakia tool, that is part of the Jakarta Velocity Project. Writing about Anakia would warrant another rant, so I will can this here (I could go on for ages about missing documentation).

What is really bad is, that it forces not only XML on an user who wants to write docs, it also forces an unusual format on people. If you insist on XML, why not DocBook? There you can use a myriad of editors which hide the XML from you. Why Anakia? Oh yes, there is a docbook plugin. It is pathetic. It is so pathetic that the documentation for the DocBook plugin is written in… Anakia documents. The DocBook plugin can convert docbook files. But they are neither integrated into the maven site, nor do they look as nice as xdoc. I think you can imagine for yourself how well accepted or widely spread they are…

Why is it bad to force an unusual style and tight “builds best with trunk” integration onto documentation? Because it leads to rotting docs. Most developers don’t like writing docs. I don’t like writing docs. But if I have to, then I want to take an editor and chug away. No thinking about markup. If I want to _underline_ something then I want to do it in the text. Not with some obscure markup. Or opening and closing sections. And the “tight trunk integration” leads to these rotting docs dragged around everywhere. You don’t want this. You want your docs split up:

• Global Documentation - Docs about the Project itself. Maybe News, Releases, Talks, Awards. Global Links. Stuff that doesn’t change much
• Release specific Documentation - Change Logs, Code Metrics, Release Notes, Javadocs. Stuff that must be reproduceable whenever a specific release documentation site should be built. There is more than just “one global site at foo.org”. Think Intranet integration. Think team documentation sites.
• Development specific Documentation - Activity logs. Changes. Stuff that changes every few days. Probably only interesting for the main (internet) development site.

Does Maven support that kind of split up? Not at all. You have to split your docs into multiple maven projects (maybe tied together by the Reactor). You cannot link well between sites, because for “off-project” links, you must know the (full!) URL. You can’t use relative links because Maven won’t translate them. And the list goes on and on.

So you might ask yourself now: What good is the Maven site for? IMHO, for the metrics of a current development process. For the kind of development process, that you see in many open source projects that are developed at high speed but never have any official releases.

And what would I recommend to use for documentation? Even if you cry out loud now: I’d recommend a Wiki. Stop. But a Wiki suffers from the same problems as the Maven site. Yes, but every time you want to make a release, you snapshot your Wiki and then use a transformer to convert it into xdocs. And then bundle these xdocs with the release. This doesn’t help you with the volatile change log and activity issues when rebuilding the release site. But it will help you tremendously with keeping your documentation up to date. Of course, building usable project documentation in a Wiki is a thing, that I don’t want to go into here. Let’s just say that you might want to have a Wiki Gardener on your team. But this is a job that can be done by someone who wants to contribute without coding skills.

In some maven-site based projects that I work on, this is clearly visible. While code development happens in the SCM, the docs buried there (as xdocs) rot away pretty heavily. At the same time, new documentation is added to the related Wikis all the time. Because it is easy. Because it is convenient. Because it works. And xdoc does not.

apache code maven xdoc

27 August 2005 | Rants | Comments