Request for comments: Documentation life cycle

We have migrated all our production docs away from a single-page doc based on AsciiDoctor to Antora.To keep our users a way to access also the old docs, we have created an archive that has all the pre-Antora documentation.

Having now a framework that supports multiple projects and versioning comes makes it now much easier to structure content. We have now a unified user experience for all the projects maintained and published in our community.

The OpenNMS project since its existence made 440 releases of OpenNMS alone for Horizon. It doesn’t include the commercial version of Meridian, ALEC, or the Grafana plugin Helm.

Screenshot 2021-07-14 at 11.24.29

With such a long life, we need to think a bit about scaling the docs and a life cycle. For Meridian and Horizon, we publish minor bugfix releases pretty regularly on a monthly interval. For the smaller projects like ALEC and Helm, we decide based on the type of issues or features tagging it with a new version number.

Request for comments: Publishing life cycle

Instead of building all versions until eternity with Antora and publishing them to docs.opennms.com, we think about introducing a life cycle that includes publishing into different places like here:

If you want to access or work with docs in unreleased versions, e.g. feature or bug fix branches you have two places to get the docs is a) getting them directly from the source and building them locally with Antora yourself locally or b) downloading a pre-build site.zip artifact from our CI/CD pipeline.

As soon we make a new release, the new version is published to docs.opennms.com. When a version number reaches the end of life, we push it to the archive on vault.opennms.com/docs to keep it available.

A suggestion for a Meridian/Horizon time window could be aligned with community support and commercial support for Meridian which means 3 years for Meridian and the last major version for Horizon before it is moved to the archive. This way a) we keep old docs available and b) we inherently communicate what version we recommend to use in production.

Feedback and ideas are very welcome.

1 Like