Versions

Your knowledge base content is subject to change. Perhaps your internal policies have been updated or the software you are documenting has undergone a major change to its interface.

You will need to update your knowledge base content and it can be really daunting to do those edits in the already published article.

You can create specific, distinct versions of an article or custom content category over time, 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 (minor, major, or custom numbering).
• Make updates/edits in the new version rather than the currently published version.
• Publish the new version in place of your existing article once the version is ready to go.
• Add editorial notes for each version to summarize what has changed or provide editorial feedback.

Some of the benefits of using versions include:

• New versions begin in an unpublished 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 publish the new version to coincide with a software release or policy update.
• Older versions can serve as back-ups and will 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.

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

Do not use versions for:

• Tracking every tiny change to an article
• Tracking 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 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: You can also wait to publish 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 are published: Since you can also control which authors can create versions and who can publish 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.

All versions for an article are stored in the Versions section of the righthand panel of the article editor:

Sample Versions section with a Version Note displayed

The current active version appears in the Active Version section.

Use the All Versions section to see a list of all versions and navigate between them. The version you're currently viewing will appear in black; click the hyperlink of another version to view that version.

Once you've opened a version, make all your changes and save them just as you would a regular article or custom content category. No changes in non-active versions will be visible to your readers unless you activate that version.

To create a version for an article or custom content category:

1. Open the article or custom content category in the editor.
2. Click the Create a new version button in the Versions section of the right hand column.
   
3. This will open a dropdown where you can select the Version you'd like to use. If this is your first time creating a version for this article, the current live article will be version 1.00. Selecting Minor Version (+0.01) or Major Version (+1.0) will create the new numbered version automatically numbered. You can also select Custom to enter your own version.
   
   
   
   Pro Tip: Minor Versions are great for small updates (text changes, new screenshots, etc.).
   Major Versions are great for large updates to your content (an internal policy change or a major software release).
4. Once you've made your selection, click the Create button.
   
5. From here, one of two things might happen:
   • If you have unsaved changes in the editor when you try to create the version, a pop-up will appear over the editor asking you what you'd like to do with those unsaved changes:
     
     You can choose to:
     • Save changes to the current version: If you select this option and then Create Version, your edits in the current version will be saved before the new version is created. You'll see those edits reflected in both the current version and the newly-created version. (This option is selected by default.)
     • Discard changes to the current version: If you select this option and then Create Version, your edits in the current version will be discarded. The current version and newly-created version will both contain the current version's content as it existed before you started editing.
     • Cancel: This option will cancel the creation of the new version and return you to your unsaved changes in the editor. This can be a good option if you want to copy the current changes without saving them to the current version.
     • Once you make your selection and choose Create Version, you'll continue to see the steps listed below.
6. If you have no unsaved changes in your editor (or you continued with the Create Version process after specifying what to do with the changes), the new version will be created by taking a copy of the current version.
7. Once your new version is created, you will automatically be taken to the new version to perform your edits.
8. You can toggle between different versions by clicking on the version number. All versions are displayed in reverse chronological order (with the most recent at the top).
   
   
   You'll see a badge showing which version is currently Published and which version you are currently Viewing. For unpublished articles (draft, deleted, etc.), an Active badge will let you know which version would be active when you published the article:
   Unpublished articles will show an Active badge next to the current active version

You can make as many changes to the new version as you'd like. They won't show until you Activate this version.

For each version of an article or custom content category, you can also add Version Notes.

This field is a free-form text field. You can use it to add notes about the content, what's changed between versions, or provide editorial feedback to other content authors in the version Note field. Version Notes are only visible in the article editor:

Sample Version Note

These notes are tied to the particular version, so you'll see different notes for each version. The text field can hold a large amount of text, and you can use the scrollbar on the right or drag the lower right corner to view additional notes:

Version Note scrolling and window resize

When you're ready, you can "activate" a new version. The active version:

• Is the default version opened in the editor
• Is the version that readers will see if the article is currently published or when it is published
• Is listed as the active version in the Active Version section of the editor
• Has the "Published" or "Active" callout next to it in the versions list (Published is used when the article has a Published or Needs Review publishing status; Active is used when it has a Draft, Ready to Publish, Rejected Draft, or Deleted publishing status)

To activate a new version:

1. Open the version you'd like to activate.
2. In the upper righthand column, check the Activate this version box in the Version Status section.
3. Then click Save.
   

You can delete a version in two ways. If you're currently viewing the version you'd like to delete:

1. Check the box next to Delete this version in the upper right.
   
2. Save the article.

From any other version, you can also click the red X to the left of other non-published versions to delete them:
Red X to the left of other versions will prompt a delete

This will open a pop-up to confirm you meant to delete this version. Click OK to complete the deletion.

If you'd like other KnowledgeOwl authors with access to the editor to review your version, you can use a two-step workflow:

1. Editing authors mark the version as Ready for Review
2. Reviewing authors can use a Manage Articles filter to view a list of articles with versions ready for review, open them, and provide feedback or activate them.

Mark version as Ready for Review

When a version is ready to be reviewed:

1. Be sure you have the correct version open in the editor.
2. Click the Ready for review checkbox.
3. Then Save.

Ready for review checkbox This will add a Ready badge to the version:

Version "READY" badge

Use Manage filter to view a list of versions ready for review

Reviewing authors can then view a list of articles ready for review:

1. Go to Knowledge Base > Manage.
2. Create a custom Manage filter with the Versions ready for review checkbox checked. You can use any combination of other filters (such as date, author, etc.). For example, this filter will pull all articles with versions ready for review that have a Published or Needs Review publishing status:
   
3. Save your filter to view the list.
4. You can also export the Manage Articles filter output to CSV--articles with versions ready for review will show TRUE in the "New Version Ready to Publish" column.

Reviewing authors can add feedback in the Version Notes field, make edits themselves, or activate the version.

Have multiple versions ready for review that you'd like to activate? You can activate versions marked Ready for review in bulk using the Manage articles bulk editing interface and this same filter!

While the in-app version review process can work well if all of your reviewers are also KnowledgeOwl authors, it's quite possible you have reviewers or subject matter experts who don't have author accounts in KnowledgeOwl.

Or you might want reviewers to be able to see that version they're reviewing live in the full knowledge base, so they can see how it will look to your readers.

This is what the Make Visible to Groups option is for: it allows you to publish a new version of an article to only specific reader groups accessing your knowledge base, so they can view that version as it will appear when it's fully published.

How it works

The Make Visible to Groups setting only appears in the righthand panel of the editor between the URL Redirect and Restrict to Groups sections. It only appears in the editor when you're viewing a not-active version. It shows all the reader groups you have in your knowledge base:

Sample "Make Visible to Groups" section When you check one of the boxes next to a group in the Make Visible to Groups section and save, this article version becomes available in your knowledge base to those groups:

1. In the Table of Contents, under the currently published version, with the version number added to the end of the title. For example:
   
   Sample version 3.00 visible to group in Table of Contents
2. Via direct URL link. Once you add one or more groups in Make Visible to Groups and save, you'll see hyperlinks in the message at the top of the version that will allow you to:
   1. Copy Version Link: copies the URL for this particular version to your clipboard, so you can paste it somewhere else (like an email, a note, etc.)
   2. View Version: Will open the knowledge base to this version in a new tab (basically the same place you'd get to by clicking the link in the Table of Contents screenshot above).
      

This version will only be accessible by readers in the groups you select in Make Visible to Groups.

Once you activate this version, the Make Visible to Groups section disappears entirely and the regular Restrict to Groups permissions apply.

We were hoping you wouldn't ask this, as it's not an easy question to answer. The short answer is: yes, revisions are automatically stored for some versions. But the long answer is: it's complicated.

We track the ten most recent revisions to an article automatically. When you create an article, that is automatically created as Version 1.00. As long as you continue with Version 1.00, revisions will be tracked on that version.

Once you create more than one version, we track revisions for the currently active version only.

After a version is activated, it continues 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 an article called "Learning to Fly" which he has published. By default, this has only one version: Version 1.0.

• Revisions for Version 1.0 are tracked, up to a maximum of 10

Linus needs to make some updates, so he creates a new minor version, Version 1.1.

• Revisions for Version 1.0 will still be tracked, since it is still the current active version
• Revisions for Version 1.1 will not be tracked because it isn't activated yet

Linus continues to save changes to Version 1.1 but has not yet activated it.

• Those changes will not be tracked as revisions, because Version 1.1 has not yet been activated
• Any revisions to Version 1.0 would continue to be tracked

Linus activates Version 1.1.

• From activation onward, revisions for Version 1.1 will be tracked
• No further revisions for Version 1.0 will be tracked
• The historical record of the last 10 revisions for Version 1.0 will still appear if I view Version 1.0 in the editor; they will not appear when I view Version 1.1 in the editor

PDFs for the current live article are generated and updated automatically when you publish an article or save changes to a published article.

But what about versions?

If you make a version visible to groups, the PDF icon isn't visible when a member of that group views the version.

Instead, you can generate a PDF of a version from within the article editor.

This PDF is available for 24 hours from the moment you activate it, or until you save changes to the version. You are welcome to download and save it, share that download with anyone else who might not have access to KnowledgeOwl, or just use it as a record of what a version looked like at a given time.

To generate a PDF of an inactive version:

1. Open the article for editing.
2. Open the inactive version you'd like to generate a PDF of.
3. When viewing an inactive version, there's a warning across the top letting you know it's a version. Within that warning, you may see several different links depending on whether this version has been made visible to groups or not.
4. Click the Generate version PDF link to generate the PDF. You can navigate away while it generates, if you'd like.
   
   Generate version PDF link when the version has been made visible to groups
   
   Generate version PDF link when the version has not been made visible to groups
5. Once the PDF is generated, the link in the warning will update to read Download version PDF. You can click that link to download the version PDF that was just generated.
   
6. Alternatively, you can download a generated PDF by clicking the PDF icon in the version list, too:
   
   Click the PDF link next to a version to download the version PDF

You can also generate a version PDF of the current active version of any published article from the editor by clicking the Generate version PDF link near the upper right of the main editor pane:

As with the inactive version PDF, the link will update to Download version PDF once the PDF has been generated, and it will appear in the version list.

Version PDFs will use whatever header or footer you've set up in Settings > PDFs. Since they can contain very different metadata from a standard article, the metadata that is available and the format for these PDFs is controlled through a Custom HTML template in Settings > Style: Article Version.

The default layout looks a bit like this (sample values are in italics):

Sample article title

Version Number 1.01
Version Author Linus Owl
Version Creation Date 10/05/2023 12:32pm EDT
Version Activation Date 10/08/2023 1:01pm EDT
Author Activating Barn Owl
Version Deactivation Date 10/10/2023 3:04pm EDT
Author Deactivating Linus Owl

Sample article body

You have a lot of control over what this looks like, so if you want to make changes, you can!

Update the text labels

To change the text labels, like "Version Number" or "Version Author", edit the default text strings in the Article section of the Customize Text tool. See Section breakdown: Article for more details on the available strings and what they adjust.

Update the format or layout

The format and structure for version PDFs is set using the HTML format laid out in the Default Article Version HTML template in Settings > Style. You can edit that template to:

• Change the order of the metadata fields
• Remove any metadata fields entirely
• Update the layout of that metadata section

If you're looking to make a specific change and you're not sure how to do it, please contact us for help! We'll be building out examples of changes you can make based on where people seem to struggle the most. 😉