Recently, I’ve been thinking about documentation more and more. I’ve just finished up some documentation for an internal product, which was all done using the maven-site-plugin and APT. This worked reasonably well: I get a generated website, with javadocs and a few howto pages I wrote.
But it really feels like it starts to fall apart when you get to a multimodule build. Maven does quite a few nice things for you, but you start to see some annoying glitches here. One of the first ones I came across was the url element. If you set it correctly in the root pom (e.g. http://mycompany.com/project/) then maven automatically appends the artifactId when constructing the site for submodules. So you end up with http://mycompany.com/project/mysubmodule/, which isn’t necessarily correct.
After thinking about this for a while, and how best to document jslint4java, I’ve come to the same realisation as Mark Pilgrim: plain old HTML works best. I’ve tried a few like Textile (yuck), Markdown (better), POD (too simple) and docbook (too complex). HTML strikes the right balance. Especially with the new HTML5 tags. And it doesn’t require any building to view it. Just hit refresh.
So how to make it part of the maven build? Easy. Stuff it into it’s own submodule. Then, it can be referenced by the assembly plugin later and put in the correct place in your distribution. Check out jslint4java-docs for details. It would be nice if maven natively supported zip packaging, but that’s easily overcome.
This does mean it doesn’t get automatically deployed to a server. But that doesn’t really matter. It happens infrequently enough that I’m happy to do that by hand where needed. Or at least find a better solution when I get bored of that. 🙂
Jabbering Giraffe 