Documentation versioning best practices with docs-as-code

Pros and cons

This is a very lightweight way to add “checkpoints” in your Git history that signify “this was the state of the documentation at the time of release”.

The main issue with this workflow is that you cannot backport fixes or make changes to old versions. You can’t change the history of your main branch (without some serious rebasing).

The good news is that when you do, you can create a new branch!

1
2
3
4
5
6
7
8
9
10
11
# Checkout the tag you want to update
git checkout v1.4

# Create a branch from this point
git checkout -b v1.4.1

# ...make your changes...

# Commit your changes
git add .
git commit -m "Updated docs for version v.1.4.1"

You have now gone back to the branch-per-version workflow!

Finally, your tools will have to support the same workflow as with the branch-based workflow: you have to be able to build your versions separately.

So, to recap:

• ✅ Simple - no need to manage multiple branches
• ✅ Works great if you know past versions will never be updated
• ⚠️ Can’t make changes to old versions without moving to a branch-based model
• ⚠️ Requires specialized support from your tools or managing multiple sites

REST API documentation versioning

API versioning is related to versioning in general, and warrants its own section. This is a nuanced topic: there is no “one way” to version your APIs, even if some best practices have emerged.

REST APIs will often be versioned independently from the rest of the product. And because you generally cannot make breaking changes without giving your users ample time to migrate, you can have multiple versions of your API running at the same time.

Stripe is a great example of an API that does this. They write about their versioning strategy here. The Stripe API expects a Stripe-Version HTTP header that specifies which version of the API you want to be using. This way the user can decide which version to use, and can update at their own pace.

When a breaking change is made, Stripe creates a new version:

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 2023-10-16.

Now any client that wants to opt into these new features or breaking changes can update their code and swap the HTTP header to the latest version.

Documenting API versions

Stripe is of course famous for its documentation, and they customize their API reference to match the API version of your account. When you update your API version, the documentation changes to reflect that.

Another way to document differences between versions is to include notes in the API reference itself. For example adding a note in an OpenAPI description field saying Deprecated since v2.4 or Requires v4.1 or later for any operations or fields that have versioning requirements.

Or, you may end up using one OpenAPI specification per API version. This may happen if your API versions live under different path namespaces (for example /api/v1/ and /api/v2/. In this case, you will likely want to allow the user to select which version of the API they are using in the documentation itself, and show the appropriate API reference.

Hosting considerations

Good tools that create documentation websites will always have some kind of versioning mechanism. You’ll want to make sure that it matches the workflow you want to use for versioning.

Here are a few versioning-related details to consider when choosing your tools.

Switching between versions

Somewhere in your documentation, you will want to give your users the ability to change the version they are viewing.

Commonly your URLs will map to specific versions too:

• Content for the default version will be under docs.mycompany.com/...
• Content for a v2 version would be under docs.mycompany.com/v2/...
• Content for a v3 version would be under docs.mycompany.com/v3/...

Access control

In some cases it can be beneficial to only allow public access to certain versions. Perhaps you only want to give preview access to a version to a specific version?

In this case, you’ll have to make sure either your hosting provider or documentation platform supports this, or you have to do some custom engineering to achieve this.

Doctave is a solution that supports this out of the box. You can create public, private, or password-protected versions and map them to any Git branch.

Releasing new versions

Eventually new releases will show up, and old versions will be removed. Your documentation has to reflect these changes.

Releasing new versions is the simpler case. Let’s say you are moving from v3 to v4. The process of updating your docs would likely be as follows:

1. You default docs (i.e docs.mycompany.com) now point to your v4 docs
2. You create a new space for your old v3 docs under docs.mycompany.com/v3

One big benefit of this is SEO. Any content that did not change between versions is still in the same URL path, and Google will keep sending traffic to the latest version of your documentation.

Deprecating old versions

Deprecating versions is more involved, if you want your old URLs to still work. This is done with redirects.

Let’s say you’re deprecating your legacy v1 version and it lives under docs.mycompany.com/v1. There will be content and links both on the internet and in your own docs pointing to this old documentation. Ideally, you want those links to continue to work. Both for SEO, but also to minimize confusion when users are faced with a 404 page.

You’ll want to add redirect rules from your deprecated documentation that will send readers to another version of your documentation.

The simple way is to redirect all links under the /v1 path to e.g. your latest version. This is easier, but can lead to confusion if your user was searching for a specific topic, and then finds themselves on an unexpected page.

The more involved (but user friendlier) way is to try to map each piece of content from your deprecated version into a corresponding page in your new documentation. This will be simple for features that exist in both versions: you can map a /v1/account-creation page to the latest version’s equivalent page (likely, /account-creation). If an equivalent page does not exist, you can fall back to sending people to the front page of your documentation.

Final thoughts

In the end, your documentation versioning strategy should match your product’s versioning strategy. The important thing is that your tools support the strategy you choose and you are able to update past versions easily.

There are multiple right ways to do versioning, so you should discuss the options with your team, and choose what is right for your situation.