Your knowledge base content is subject to change. Perhaps your internal policies have been updated or the product you're documenting has undergone a major change.
Whatever the reason, you need to update your knowledge base content. But you might want to be able to stage those changes and decide when you want them to go live, or perhaps you want to preserve the history of what the content used to look like.
That's what versions are for.
Create versions of an article or custom content category to reflect changes to the content. Versions are basically a permanent snapshot you create of the article at a given time. Only one version of an article is published in your knowledge base at a time.
With versions, you can:
- Create different Versions of your articles to make edits that aren't immediately live or preserve the history of content for compliance or rollback purposes.
- Make updates/edits in the new version rather than the currently published version. These edits aren't visible until the version is activated, so you can stage or share them with others for review.
- Activate the new version once it's ready to go. This replaces the live article's content with the active version's.
- Add version notes for each version to summarize what has changed or provide editorial feedback. Only authors editing the content can see these notes.
Some of the benefits of using versions include:
- New versions begin in an inactive status, so you can make as many edits as you want to that version instead of the currently published article. This means your readers never stumble across an in-progress edit.
- Versions allow you to create an updated article ahead of time and then activate the new version to coincide with a software release or policy update.
- Older versions can serve as back-ups and allow you to easily reference historical content--particularly helpful if you accidentally removed a section you still need or need to provide an audit history of previous documentation versions.
- Unlike revisions, versions are stored for as long as you'd like them to be.
- You can add version notes to summarize changes that were made or track content reviews.
- You can create versions for both articles and custom content categories.
- Edit the body content and the title in a version.
Generally, people use versions to:
- Keep an audit history of different versions of content used over time.
- Provide version control for their documentation.
- Match documentation updates to real-world updates (such as releases, etc.).
- Prepare updates for published content without having to instantly publish them.
Don't use versions to:
- Track every tiny change to an article
- Track every person who's edited an article over time
For version control: When you create a new version, it takes a copy of the current active version to use as a starting point. Any edits you make to one version don't impact another.
For releasing updates to an already-published article when you choose: Wait to activate a new version until all editing and review is done--this can be a great way to prep documentation updates ahead of major company announcements, rebranding, product releases, a new school year, etc. without impacting the current published article.
For allowing a review of updates to a published article before they're live: Since you can also control which authors can create versions and who can activate them, versions can be a great way to allow folks to edit and update articles without giving them access to edit a currently-published article.
Version comparisons
We don't have an automatic version comparison to highlight the differences between versions, like we do for revisions. For now, manually compare versions or have detailed Version Notes highlighting the differences.
Revisions are stored for all article versions created or edited after 12 April 2024.
As with regular articles, the Recent Revisions link appears in the upper right of the editor once a version has been saved twice after its creation.
Not applicable for older versions
Until April 2024, we only stored revisions for the current active version. We began tracking revisions for all versions on 12 April 2024. Versions created or edited before 12 April 2024 didn't have full revision tracking. For questions about revision history in older versions, refer to the Older versions section below.
Older versions
Versions created and last edited before 12 April 2024 don't have their full revision history tracked.
For older versions, revisions were only tracked for the currently active version.
After a version was deactivated, it continued to hold the revisions it had from when it was activated (max of 10).
Let's look at an example to see how this plays out:
Linus has a published article called "Learning to Fly". By default, this has only one version: Version 1.0.
- Revisions for Version 1.0 are tracked, up to a maximum of 10.
Linus needed to make some updates, so he created a new minor version, Version 1.1.
- Revisions for Version 1.0 are still tracked, since it is still the current active version.
- Revisions for Version 1.1 weren't tracked because it wasn't activated yet.
Linus continued to save changes to Version 1.1 but hadn't activated it yet.
- Those changes weren't tracked as revisions because Version 1.1 had not yet been activated.
- Any revisions to Version 1.0 were still tracked.
Linus activated Version 1.1.
- From activation onward, revisions for Version 1.1 are tracked.
- No further revisions for Version 1.0 were tracked.
- The historical record of the last 10 revisions for Version 1.0 still appears if he views Version 1.0 in the editor; they won't appear when we view Version 1.1 in the editor.
