The Maven plugin Buildmetadata Maven Plugin has been released with version 1.4.0.

This version of the plugin provides support Git (experimental) and encrypted passwords. We also removed the dependency to the parent POM.

For details on this version of the library please visit the project's homepage, for changes since the last version, please consult the release report.

For our projects we provide documentation sites for each released version. This way users have always the documentation for their chosen version available.

In this article we discuss the pros and cons of this approach and show our strategies to mitigate the problems we identified.

Examples

First let's have a look at some example documentation sites to get a feeling what strategies are currently used by the open source community. This is not an extensive list and puts only a flashlight on some approaches.

JBoss

JBoss provides information about each minor version of their JBoss AS, Infinispan, GateIn Portal and other projects. For Arquillian Graphene documentation wikis exist only for major versions.

To get an overview on the documentation wikis provided by JBoss, please visit the Project Documentation Editor Dashboard. Here are a few examples:

Versioning at JBoss

The strategy for these projects is that there is no significant change in documentation within minor or micro (aka bugfix) releases.

Apache Commons

Apache Commons projects provide the API documentation for their latest major releases (e.g. Lang) or for some of their minor releases (e.g. IO), but publish only the documentation site for their latest release (which may happen to be the current SNAPSHOT version).

Versioning at Apache (Commons Lang)

Versioning at Apache (Commons IO)

The later approach follows the strategy that the project team knows best, when a new API documentation should be made available and that of an old version should be kept for reference. The site containing additional information, is not versioned.

Versions Maven Plugin

The Versions Maven Plugin at Codehaus only provides a documentation site for their latest version.

Versioning at Codehaus (Versions Plugin)

The documentation shows, since which version which configuration option is available (e.g. set-mojo) and you may download the sources and API documentation for each version from the public Maven repository.

This is a strategy most Maven plugins follow. One site and each bit of information clearly addresses which version it supports.

smartics

At smartics we provide a site for each released micro version.

Versioning at smartics

We also add a canonical link that points always to the latest release version and add easy to remember links to the individual versions.

For instance the canonical URL

always points to the latest version. If you are using an older version, say 1.2.0, you simply add this version to the URL like this

In newer versions the All Versions link points to a listing of available versions:

Examining our Strategy

The Pros

We do not want to demand users to upgrade to a newer version, if they are happy with the version they are using currently. Tools are for developers to make their lives easier, not for keeping them busy to install the latest version that provides features they do not need. We also do not want to bother users of older versions with information they have not requested, because their version in use does not support it. And last but not least, if a version is not backward compatible due to removed features, users of an older version still have access to their documentation.

The automation process for each release is identical. This makes its handling easier.

This is not that we deem our way of releasing superior over other approaches. It is just the way we handle our versions.

The Cons

There are also drawbacks. Search engines find older versions of sites or users may simply discover a link to an older version on the internet. In both cases the user is not directed to information on the latest version of the product and might not even be aware of it.

How to solve the Problems?

So what can we do to help our users to get informed about the availability of new versions?

Latest Link Ribbon

The old versions of sites are still be linked and indexed by search engines.

To make the user aware that the version s/he is currently looking at, is not the latest version, we introduced a ribbon in the upper right corner.

The latest version shows this ribbon:

This ribbon is removed by CSS once the page is fully loaded. Therefore the latest version of the documentation usually shows no ribbon.

Deprecation Ribbon

In addition of the problems mentioned above, projects that were renamed impose another obstacle. Users simply cannot know, what the new version is named and may never switch to it.

We changed the names of some of our projects. For instance the buildmetadata-maven-plugin was once called maven-buildmetadata-plugin, until we found out that this name is reserved for plugins owned by the Maven team.

To make the name change visible to our users, we added a ribbon to the right corner of the plugin's pages. Clicking on the ribbon will move the user to the latest version of the project.

Latest Link

From this year on we will add a link to the project sites that provides a link to the latest version. This will be a minor improvement to help visitors of a site to check by themselves with one click, if a newer version is available.

All Versions

Each project usually provides a link on the left menu column called All Versions. On clicking this link a list of versions for this project will be displayed.

Users get an overview on all releases (and in case the current snapshot) by one click.

Release Notes on our Sites

Each site provides a report on the release. This allows users to get informed about the latest changes and what is planned for the future.

The reports are generated with our issues-maven-plugin.

Release Notes on our Blog

Our users have difficulties to distinguish between links pointing to the current version advertised in a release note and the latest version available.

Therefore we will try to make this difference obvious by adding the following box:

 

Conclusion

Providing multiple version of a product to the community is much work. At smartics we follow the philosophy that information is far more often read than created or edited. Therefore it is logical to add more work on editing to lower the amount of time spent by users to find information.

Thanks to our automation toolbox we are (often) able to reduce the work on our side, too!