Product docs reloaded - semantic versioning meets continuous delivery

[#1]

In this article, I’m going to share how I use Confluence to tackle documentation for a product that needs both semantic versioning and continuous delivery. And, in the process, dispel the myth that ‘Confluence does not support semantic versioning’.

Nevermind the GitOps, Here’s Confluence

Obligatory warning: This is an advanced product documentation content management stuff. It borders on metaphysics. But it works, it’s award winning & customer succes story inducing :), it makes our lives much easier and customers happy. And you will find it useful WHEN you migrate from Data Center to Cloud.

Just to ensure we’re broadly on the same page.

• Continuous delivery (CD)
  You ship incremental updates to your product the moment they’re ready - including documentation, of course. Two times a day, once every sprint, as they come, every two weeks… The point is that your product is one-version-fits-all, there’s no ‘next’ or ‘previous’ version.

• Semantic versioning (SemVer)
  You ship your product - ideally with documentation, of course, in clearly defined installments that are identified by a string of numbers. Like 9.2, 3.5.17, and so on - major.minor.patch. Typically, users can decide when, or whether, to update.

Each strategy comes with different challenges from the point of documentation. CD is typically handled with a doc-as-code approach, SemVer often too, but unless you’re an open-source enthusiast, the common path is to choose a ‘proper’ documentation tool.

It’s only logical, then, that I’m using Confluence to take care of both strategies for a single product :) .

Previously, on 'Ship Happens’

At Emplifi, we have one main product documentation site for our core platform' features - https://docs.emplifi.io/. A two-week release cycle, more swimlanes than you can count on your hands, and Confluence with a couple of apps is a perfect tool for that.

But we have another product with its own documentation site - Emplifi Agent. A major release, with a number, happens every six months. In between, things are interesting.

• A new release is published. Currently 12.4. This is now the Production version. Version 12.3 is retired.

• Development of 12.5 continues; updates are released and documented in the Training version as needed.

• Occasionally, a hot-fix is released and must be documented in both the Production and the Training version.

• A couple of weeks before 12.5, Training docs are updated with the Release Candidate 1 release notes and corresponding documentation. This is later followed by RC2 updates and release notes.

• 12.5 is released with all updates. At this moment, the Production and the Training versions are identical.

This hybrid release strategy allows our customers to access documentation for pre-production releases in the familiar environment and easily switch to the latest official version.

MadMax to Confluence

Agent is a very complex product, and we rely on developers and QA engineers to draft doc updates. This was made much easier once we migrated Agent documentation from MadCap Flare to Confluence. The connection between Confluence and Jira makes tracking and procedural matters much easier than ever before.

It was obvious that Agent’s release cycle requires a slightly different approach than outlined here and here and that we use for the Emplifi platform docs.

When worlds collide

I kept the basic workflow and the two-space approach that syncs not just the content that was approved but also third-party app’s metadata (Scroll Documents). I’m using Appfire’s Comala Document Approval and Publishing but pretty much any workflow and space would do the job.

Now, Scroll Documents supports semantic versioning out of the box. You work in your Confluence space where you have a Scroll Document created, update your pages in the so-called ‘working version’, and when you’re happy, create a snapshot of that Scroll Document. Name it, publish it to Scroll Viewport, and voila, you’ve got your semantically versioned documentation - just like that Atlassian’s Confluence DC docs (created using the tools and method I just described).

That’s cool, but it does not address the need

• to keep pushing intermittent updates

• to work with two synchronized Confluence spaces

  • authoring/workflow source space

  • target space with approved synced content that feeds the Viewport site

So I needed to do two things:

• Make the good folks at K15t roll their eyes :) . Again
  I achieve this by using the Scroll Docs’ ‘working version’ to feed the Viewport site. But it’s OK because of the two-space strategy…. I guess...

• Create versions (snapshots) in the target space.
  This is logical because the target space features approved content only.

It was clear that I needed to work with a single source and separate it into two content streams that I can treat (edit) independently … while preserving my unrestricted workflow freedom.

Fork Yeah: continuous delivery meets semantic versioning

Without much ado, the crucial thing was to realize that I do not need a point of separation in the docs but rather a moment in the process where I would create an off-ramp (slip road in US EN, fork in Git….). Also, I had to give K15t product managers a new reason to roll their eyes :) .

So how does it work?

• There is a direct pipeline from the authoring source space, through the target space, to the Training documentation version of the public documentation. This makes continuous delivery possible as it gives us the option to update any page at any time while we can keep any number of pages as drafts or under review.

• Snapshots are created in the target space and become the content source of the Production version. One at a time. Crucially, snapshots are easily editable if needed (eyes roll :) ).

Another benefit is that the URLs for both the Training and the Production pages stay the same, no matter which semantic version is actually live - which is perfect for this use-case.

Of course, I could keep the previous versions on the documentation site too.

Confluence, the final frontier

Creating this solution was particularly rewarding. It was one of those implementations where you spent one week meeting and talking to people, one week agonizing over how to approach it… and then you have the Eureka moment and build it with a couple of clicks in half an hour

It is deceptively simple because it just works flawlessly and removes a ton of in-content dependencies. But it needed a rather creative approach to using AND connecting apps from different vendors.

So don’t be afraid to create chains or clusters from marketplace apps. Confluence will take you as far as you dare and, as you can see, you can go pretty far.

With changes coming to app editions, pricing strategies, and bundles, you’ll have even more options to get creative without overstretching your budgets.

[Dave Liao]

@Kristian Klima - Kristian, love the section headers of this article! ✨

Another benefit is that the URLs for both the Training and the Production pages stay the same, no matter which semantic version is actually live

Thanks for sharing how you get your product docs out and updated - and how the sync methods preserve URLs, a challenge for many teams who rely on Confluence for customer-facing product documentation.