Decouple Your Software From Its Documentation

As a programmer who hasn’t been living under a rock for the last couple of years, by now you sure know that loose coupling of software components enhances their reusability. When it comes to OOP, there are a lot of tools in our box to implement loose coupling, including Program To An Interface, Dependency Injection and many more. But what about software documentation?

If you are using Apache Maven, you probably know - or better use - the command mvn site to generate the documentation of your software product. In case you don’t know Maven, this command uses the maven-site-plugin to generate a static website from the declaration of your project in its Project Object Model (POM) file pom.xml. By editing a Site Descriptor file src/site/site.xml, it also supports adding custom pages in various input formats - my favorite is APT.

The Issue

By default, the generated website will show the version information ${project.version} from the POM in its banner. At first sight, this seems to be a good feature because letting your users know about the latest version is always nice, isn’t it? Well yes, until you want to update the website content from a snapshot version of your software, not from a release version. And then you will get something like this:

Notice the snapshot version in the website banner. This version number is a misleading information to your users because whatever it may mean, it’s not available anywhere! As a Maven user, you know that this version number just reflects the schema applied by Maven to development builds. But you can’t expect your users to know that and after all, they shouldn’t even care - it’s just your developer build.

Independent Life Cycles

The key to this issue is to realize that software and its documentation may have separate life cycles! Your documentation sure depends on your software, but you might actually need to publish updates to it a lot more often than a release version.

For example, soon after the latest release of your software, you might get new frequently asked questions and therefore you should update the FAQ in your documentation. You will certainly need to do this because you can’t anticipate all questions. Even if your software doesn’t come with an FAQ, there are a lot more examples of why you might need to update and publish your documentation more often than your software, but I spare you from them.

The Fix

Now with Maven, the resolution is easy. Just update the Site Descriptor file src/site/site.xml as follows:

<project>
    <version position=none/>
    <!-- ... -->
</project>

This will instrument Maven’s Doxia content generation framework not to output the version number on each and every page anymore. The result may look like this:

Notice that there is no version in the website banner anymore. Are these all references to the version number? No! There is at least one more reference in the project’s coordinates on its summary page file project-summary.html. This file is generated by the maven-project-info-reports-plugin. There are several options how to fix this:

  • You could configure the maven-project-info-reports-plugin not to generate this report.
  • You could deploy your site to a directory before uploading it and manually edit the file. You’ld have to repeat this step everytime you want to publish an update to your website, however.
  • If you are using the maven-release-plugin, you could check out the latest release from your SCM and apply all documentation updates only to this branch. You’ld need to merge all changes into the main trunk again before the next release however.

My personal preference is to avoid these complications and leave it as it is. So right now, you’ld see 7.0.1-SNAPSHOT as the version on this page.

Enjoy TrueZIP!