Versioning and history

Use article versioning to manage new iterations of your content, and learn how KnowledgeOwl handles article versions and article history.

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.

KnowledgeOwl allows you to:

  • Create different Versions of your articles (minor or major versions).
  • 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.

Setup

  1. Access the article that you need to update.
  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. This will create a new version by taking a copy of the current version. Once your new version is created, you will automatically be taken to the new version to perform your edits. 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).


    Note: 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.

Version notes

You can also 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:

gif showing the version note field scroll and window extensionVersion Note scrolling and window resize

Activating a version

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.

Deleting a version

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.

Version review process

You can also use a review process before publishing versions. When a version is ready for review, click the Ready for review checkbox. Then click Save.

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

Version "READY" badge This status will also show up in the Manage articles CSV export as TRUE in the "New Version Ready to Publish" column.

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.

Version review process using "Make Visible to Groups"

One of the challenges people face using versions is getting feedback on changes before the new version is published. If your reviewers have access to your knowledge base, they can come in and read it in the editor or click the Preview button for the version. But sometimes you might need to get feedback from subject matter experts and others who don't have administrative access to your knowledge base. Or you might want reviewers to be able to see that version live in the full knowledge base.

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 unpublished article versions, between the URL Redirect and Restrict to Groups sections. It shows all the reader groups you have in your knowledge base:

Sample "Make Visible to Groups" section When you add a group in the Make Visible to Groups section and save, this makes the article 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. The URL for a version is the normal URL of the published article with /v/[version number] at the end, where version number is the number for that version. So, for example, if I am working on this article (current published URL: https://support.knowledgeowl.com/help/versions), and I've created version 3.00 and made it visible to groups, my reviewers can use https://support.knowledgeowl.com/help/versions/v/3.00 to access it.

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

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


What kind of article change history does KnowledgeOwl keep?

Your knowledge base can track two types of change/edit history for a given article:

  • Revisions: stored automatically; temporary history of text changes only
  • Versions: full record of everything in the article; must be manually created; preserved as long as you wish

Let's explain these in a bit more detail.

Revisions

What are they?

After you've created an article and saved it for the first time, a revision is automatically logged every time you save an article with some type of change and click the Save button. This means that each revision could be something as small as a corrected typo or changed punctuation mark, or as big as replacing all text of the article. Recent Revisions capture changes to the article's text only. So if you just replaced one screenshot for another, that won't be captured.

Revisions are basically the most recent save log for the article.

If you're using shared content articles, all revisions for both child and parent article are stored and displayed at the parent article. The child article has no revision history of its own.

How many are there?

We automatically save up to ten (10) recent revisions. Once you have saved more than ten times, we'll automatically delete the older revisions to maintain a maximum of ten.

Where can I see them?

You can see when revisions have been stored by looking just under the Save, Preview, and Back buttons. If revisions have been stored, you'll see a Recent Revisions hyperlink with the number of revisions in parentheses:

Sample Recent Revisions link

Click that link to view a list of your recent revisions:

Sample Revisions List

The most recent revision will be at the top, as Revision #1. It will only give you the option to Compare to Previous Revision. The oldest revision will be at the bottom.

You can use the Compare to... links to compare any given revision to:

  • the Previous Revision (the one immediately below it in the list) 
  • the Current revision (Revision #1)

If you have fewer than 10 total revisions, you'll also have an option to compare that oldest revision to the Initial Draft, which allows you to view the first content save for the article.

Clicking on one of those comparisons will open a new screen that will do a side-by-side comparison:

A sample Revision Comparison on this article

The exact display will depend on whether you chose the Compare to Current or Compare to Previous Revision options. The screenshot above is the Compare to Current, which shows the current content on the right.

  1. The Content section will show the Author listed at the time of save, as well as the date + timestamp of the revision's save.
  2. The Title lets you compare the article's main title between the two revisions.
  3. The Toc Title lets you compare the article's Internal Title (if there was one) between the two revisions.
  4. The Publishing Status lets you compare the article's publishing status. 
    Note: you won't see a publishing status for revisions saved prior to 15 July 2020.
  5. The Body Text section lets you compare the article's text between the two revisions. 
  6. Any deletions will be in red font and strikethrough.
  7. Any additions in a revision will be in green font and underlined.
  8. You can revert to this revision by using the Recover Revision button.
  9. Use the Newer and Older buttons to cycle through revisions without returning to the Revision List

How can I use them?

Think of revisions as a snapshot of the most recent changes to an article, and an "oh no what have I done?" protection if you've recently made changes and messed something up.

Generally, people use revisions to:

  • See who's edited the article recently, and how substantive those edits were
  • Recover a recent revision of the article when something's gone wrong (someone accidentally deleted things or misunderstood what edits to make, etc.)

Do not use revisions for:

  • Long-term auditing/tracking of content changes
  • Permanent record of content to be able to revert/show what the content was at a specific point in time (such as for a compliance audit, etc.)

When you click Recover Revision, the editor will take the revision snapshot of the article you recovered and insert that into the editor. Those changes will not be saved/displayed until you click the Save button in the upper right!

Versions

What are they?

You can create specific, distinct versions of an article over time, to reflect changes to the content. These versions are stored as long as you'd like them to be. You can store Version Notes for each version, as well.

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.

How many are there?

You can create as many versions as you'd like. We have default major and minor version numbering options, but you can also custom number them in ways that make sense to you (to coincide with annual audits, software or product releases, etc.).

Where can I see them?

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 version you're currently viewing will appear in black; click the hyperlink of another version to view that version.

How can I use them?

For more information on using Versions, see Versions.

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 users 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.

At this time, we do not have an automatic version comparison that will highlight the differences between versions, like we do for revisions. For now, you'd need to manually compare versions or have detailed Version Notes highlighting the differences.

Are revisions stored for versions?

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 and publish it, 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 published version only. After a version is unpublished, it continues to save the revisions it had from when it was published (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 published version
  • Revisions for Version 1.1 will not be tracked because it isn't published yet

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

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

Linus publishes Version 1.1.

  • From publication 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