# Documentation versioning best practices with docs-as-code

DevFeed: [Documentation versioning best practices with docs-as-code](<https://devfeed.tech/articles/documentation-versioning-best-practices-with-docs-as-code-30947.md>)

Original publisher: [Read original article](<https://www.doctave.com/blog/documentation-versioning-best-practices>)

Author: Niklas Begley

Published: 2023-10-20T07:00:00Z

Content type: tutorial

Language: en

Sources: [Doctave - Build beautiful developer portals with docs-as-code](<https://devfeed.tech/sources/doctave-build-beautiful-developer-portals-with-docs-as-code.md>)

Topics: [Documentation](<https://devfeed.tech/topics/documentation.md>), [Git](<https://devfeed.tech/topics/git.md>), [releases](<https://devfeed.tech/topics/releases.md>), [Development](<https://devfeed.tech/topics/development.md>)

Tags: [best-practices](<https://devfeed.tech/tags/best-practices.md>), [blog](<https://devfeed.tech/tags/blog.md>), [development](<https://devfeed.tech/tags/development.md>), [docs-as-code](<https://devfeed.tech/tags/docs-as-code.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [git](<https://devfeed.tech/tags/git.md>), [releases](<https://devfeed.tech/tags/releases.md>), [version](<https://devfeed.tech/tags/version.md>)

## AI overview

This tutorial explains how to version documentation alongside software releases in a Git-based docs-as-code workflow. It covers semantic or date-based versioning, release branches, hotfixes, patch releases, and cases where product versioning is unnecessary but API versioning may still be needed.

## Source excerpt

Many software products end up having multiple releases over their lifetimes. When this happens, the documentation needs to be versioned along with the product. In this post we will look at documentation best practices when using a Git-based docs-as-code workflow. Software versioning basics Before going into how we should version documentation, let's take a look at how software projects generally handle versioning. Disclaimer: there is more than one way to version software. The method outlined in this post works for many projects, but there are other valid workflows too. Versioned releases Products like Windows, PostgreSQL, or React JS all have versioned releases. Every once in a while, depending on their release cadence, a new version with new features is released. A long list of versions for PingCap's TiDB documentation Different projects will use different versioning schemes, but Semantic Versioning is a popular way of giving structure to your version numbers. Another option is using a date-based scheme. Usually, different versions are managed in separate Git branches. A typical branching strategy is to have all work for the upcoming release happening on a main or development branch. Then, when a new release is ready, a new branch is created from the main branch and named after the release (for example v4.0). 1 2 3 4 5 6 7 main # Development happens in this branch * | v4.0 # New branch for the release * * | / * ---- | There's a few reasons for this. Firstly, it's clear what code belongs in the release, and what does not. But importantly, you can apply hotfixes to the release branch: 1 2 3 4 5 6 7 8 9 main * | v4.0 * * # <- New hotfix commit | | * * | / * ---- | This allows you to update and fix the 4.0 version, while you keep moving forward in your main branch towards the next release. Perhaps you'll even release a patch release with bug fixes: a 4.0.1. This strategy also makes it clear which features and commits belong to which version. You don't have code for multip