I am feeling that I must write down this. As I was saying yesterday I convinced myself to give a chance to Maven for its site and/or xdoc goals. After passing through a number of files and looking into some CVS projects on my harddrive I have succeeded in creating the project.xml (the POM – in my mother language this means tree [blink/]). Continuing on the same tracks I have written also my maven.xml and some little xml-s for my documentation. Till now nothing too difficult.
I start playing with the colors for the site and after a while when I felt confortable with it I have tried to move the new colors to the xdoc properties (this task consumed me a lot because I can say I am pretty blind when it comes to web design and also web colors). And here comes the surprise: after matching the CSS classes to the property names and running again nothing happened. I have checked again the documentation and for a while I have tried to fix this, but no chance. Now I find myself stareing at it and keep asking: what is going on????
Maven (bad) experience
Filed under personalog
mindstorms 
One question… why? Of all of Maven’s terrible features, the website generation and xdoc has to be the very worst. The websites it generates are poorly designed and next to useless for the very users that the site is meant to serve. In addition, Maven generates invalid HTML! You’re better off with plain xhtml, css and a bit of scripting and/or makefile to skin your xhtml and automatically upload generated files to your web server.
First of all thanks for the post.
As I stated yesterday for me writting html is not an option and moreover I do not consider a good idea to keep the project documentation in HTML format. Maybe one solution would be to write custom XML and custom XSL to have my site generated out of project documentation. But I would rather go for an existing solution than to recreate the wheel (even if for the moment it seems I cannot find this wheel).
About the HTML generated by Maven I don’t know exactly what to say. I’ve tried it into Firefox + Mozilla and IE and looks the same (maybe it tricks three of them). The site format is not so far from my expectations.
I think in the near future I will go to the solution suggested by Andreas and Matt. Having the documentation in XML will allow me to easy translate it.