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

Just to provide some common ground when we talk about version numbering, we should follow this format. Semantic Versioning 2.0.0 | Semantic Versioning

<version core> ::= <major> "." <minor> "." <patch>

As an example: 28.0.2, 28 is the major version, 0 is the minor version, and 2 is the patch version.

Another idea that came up during discussions is just to publish the latest minor version to the docs repository and move any older patch release to the archive

Pro:

  • Less search overhead, we only search within the latest minor version instead searching across all minor versions

Cons:

  • Older versions are harder to reach, with a patch release, we don’t add/remove features and the docs will still apply within a minor release
  • We wouldn’t have content very long available in the official docs to keep search indexes happy

For this reason, we can add features in a minor version, for example in 28.1.x - we would need to keep 28.0.y docs available.

2 Likes