Skip to main content

Versions and history

Every controlled document keeps a full version history. You can upload a new revision of a file document, read any past version, compare two versions, and download the file behind a specific version. Each version carries its own change reason and timestamps.

Who this is for

Administrators upload revisions and review history. Reading historical versions is available to anyone who can see the document.

Two separate axes: revisions and languages​

A controlled document has two independent axes, and the detail page keeps them separate:

  • Revisions are the change-control history over time (v1.0 → v1.1 → …). Each revision is approved and made effective in turn; only one revision is the current effective copy.
  • Languages are translations of a revision. A translation is a sibling version that does not become the current copy; it stays linked to the revision it was translated from and is flagged outdated if that revision is later superseded.

The document detail page is one continuous view: a properties summary at the top, the version history as the main body, and the used by trainings summary below it.

The properties summary​

The top of the page shows the facts an auditor checks first, always visible: the owner, the effective date, the next periodic-review date (flagged when overdue), and the reading form. When a translation is awaiting review, or a training needs revalidation after a document change, a pending indicator appears here and jumps you to the right section. Select the clearly labelled Show all properties button to open the full detail in a panel on the right. Its panel icon and tooltip provide the same cue anywhere this pattern appears:

  • Identification holds the document code, category, scope, and department.
  • Lifecycle and review holds the current version, effective date, the next periodic-review date, and the created and last-updated timestamps.
  • Ownership holds the document owner and who created it.
  • Format and source holds the type (Content or File), the file type, the original filename, and the reading form.
  • System identifiers holds the permanent document and version IDs that auditors cite, with a copy button on each.

Quality Admins edit the document code, owner, next review date, and reading form in place using the compact edit button next to the value. Its outlined edit symbol sits on a clear button surface, and the tooltip names the exact property that will change.

The version history​

The version history lists every revision as its own card, newest first, with the current effective revision expanded. Each card shows the revision's number, lifecycle badge, dates, and change reason, plus the actions you need:

  • Read opens the revision in the full-screen reading page, in the language you have selected.
  • Compare with current shows a paragraph-level diff against the current revision (not shown on the current revision itself).
  • Download retrieves the stored file for that revision, and Download original the retained source file when one exists.

A collapsed card carries a small translation-coverage chip (for example 1/2) whenever your organization has more than one content language, so you can tell at a glance whether a revision has all its translations without opening it. It counts the source language plus every live translation against the total, turns amber when a translation is outdated, and stays muted while one is still missing or in review.

Expanding a card reveals the language bar (one chip per language your organization has enabled, with the source language marked and an amber dot on any outdated translation) and the trainings that cite that revision. Selecting a language chip shows that copy's own status and actions. Read it, download it, or move it through its review lifecycle (submit for review, approve, make effective). This is true for the source language as well as each translation, so a version's lifecycle transitions always live on its own card rather than in a separate bar at the top of the page. A missing language offers the translate or upload action instead.

Screenshot pendingVersion history with the current revision card expanded, language bar and per-version trainings visible

A revision starts as a draft​

Creating a revision never changes what readers see. A new revision is a draft, and the copy currently in force stays in force until the revision has been submitted for review, approved with an electronic signature by a different person, and made effective. Only that last step moves the document to the new revision, supersedes the previous one, and re-indexes the content.

This means you can prepare the next revision at your own pace. Readers keep opening the effective version, the people obliged to acknowledge the document keep their existing obligation, and nothing about the change reaches them until it is released.

One revision at a time. While a revision is awaiting a decision, the button to start another one is not offered. Withdraw the revision in review, or wait for the decision, then start the next one. This keeps the change-control history a straight line.

An unsubmitted draft is continued, not duplicated. If you already have a draft revision that has never been submitted, the button says Edit draft (or Replace draft file) and your work goes back into that same draft, keeping its version number. You do not accumulate half-finished revisions on the way to one submission. Once a revision has been rejected, revising it starts a fresh revision instead, so the record of what was rejected stays intact.

Upload a new revision (file documents)​

For file documents (uploaded Word or PDF), you add a new version by uploading a revision rather than replacing the file:

  1. In the version history, select Upload new revision next to the Versions heading.
  2. Choose the new file.
  3. Enter a change reason of at least 10 characters.
  4. Upload.

The new file is stored as a draft revision, and the previous file remains the current version until the new one is approved and made effective. The revision is recorded as an upload_document_revision audit event.

Revisions are server-side and audited; the change reason is mandatory

The revision is committed by the backend, which records a fail-loud audit event and reverts the upload if that record cannot be written. A controlled-document version always carries a documented change reason of at least 10 characters. ISO 9001 expects a justification for every change. See the Compliance area.

For content documents, you create a new version by editing the body instead. The affordance sits in the same place, next to the Versions heading: Create new revision when the document is published, or Edit draft when you have a draft in progress. See Creating documents.

Publish the revision​

A draft revision reaches readers through the same three steps as a first publication:

  1. Expand the revision's card and select Submit for review.
  2. A Quality Admin who is not the author approves it with an electronic signature.
  3. Select Make effective.

At that point the revision becomes the current version, the previous revision becomes Superseded, the document's indexed content is refreshed, and everybody obliged to read the document is notified that it changed. Submitting a revision never affects the document's own status, so a published SOP stays published, and readable, throughout its next revision's review.

The full transition table is on Lifecycle and approval.

Read a historical version​

To read a specific past version, expand its card and select Read. The viewer opens that version's content and shows a banner telling you that you are reading a historical version, with a link back to the current effective version. This lets an auditor deep-link straight to, say, v1.0 of a now-obsolete SOP without leaving the app.

Each content version keeps its own stored body, so older versions stay readable even after the document has moved on. The viewer also has a print option for a clean printed copy.

Choose the default reading form​

Every document has two possible reading forms. Original pages shows the uploaded file rendered page by page, exactly as it looks on paper; Structured text shows the re-flowed text version, comfortable on any screen and searchable. An admin picks the form readers land on per document, from the Reading form property on the detail page. The toggle between both forms stays available in the viewer whenever original page renders exist, and a document without renders always opens as structured text. Uploaded file documents default to original pages; documents authored or converted in the app default to structured text. The original file remains the governing record in either case.

Screenshot pendingViewer showing a historical version with the "you are reading a historical version" banner

Upload a file in another language​

File documents are multilingual too. In the version history, expand a revision, then pick a language chip that is not yet translated and choose Upload [language] file. Provide the translated file and a change reason. Better Comply stores it as a language variant of that revision: it does not bump the revision number or become the current copy, and the original file stays the governing version. Content documents instead offer Translate to [language], which opens the editor.

When a document translation provider is configured, the same spot also offers Translate file with AI: the original file is machine-translated preserving its layout, so the result keeps the look of the source document. Text length changes between languages, so the translation is faithful in style and structure but never pixel-identical to the original. Like every translation, it arrives as a draft; a different person must review and approve it with an electronic signature before readers see it. The full walkthrough, including provider setup and troubleshooting, is on Machine translation.

When you first upload a file document you also choose its master language, which stamps the v1.0 version so the language bar knows the source language.

Every translation needs review and approval​

A newly saved translation always starts as a draft, whether you uploaded a translated file or produced it with AI assistance. Readers cannot open it yet. To publish it, submit the translation for review and have it approved with an electronic signature, then make it effective. The approver must be a different person than whoever created the translation, so a translation can never publish itself. Once effective, the translation becomes the copy readers in that language see; the document's governing version does not change.

Read a translated version​

In the version history (and in the full-screen reading page) choose the language chip you want to read. If an effective translated variant exists for the selected revision, Better Comply opens it. A translation that has been approved but not yet made effective is not shown to readers, because it has not passed the make-effective release step. If no effective translation exists, the page keeps the available version and shows a fallback banner.

Translated variants are linked to their source revision. They do not replace the document's current effective version, so the original governing copy remains stable while multilingual readers can access reviewed translations.

Compare two versions​

To see what changed between a past version and the current one, select Compare with current on a historical row. A side panel opens with a paragraph-level diff: added, removed, and changed text are marked, with counts so you can see the size of the change at a glance.

This answers the common audit question "show me what changed from v1.0 to v1.1" without downloading both files and comparing by hand.

The comparison works for both kinds of controlled document. For a document you authored as Markdown, it compares the document text directly. For a document you uploaded as a file (PDF, Word, and so on), it compares the text the system extracted from each version, so you still get a readable, paragraph-level diff instead of a download-and-eyeball.

Screenshot pendingCompare-with-current panel showing the version diff

Download a specific version​

When a version has its own stored file, a Download action appears on its row.

When you download a Superseded or Obsolete version, Better Comply shows a warning first, so it is clear the copy you are about to open is historical and not the current effective document.

Download the original of a converted version​

When a version was created by converting an uploaded file to Markdown, a Download original action appears on its row. This downloads the original uploaded file the Markdown body was derived from, which is kept as provenance on the version. Use it when an auditor needs to see the exact source document the editable content came from. See Import a Word or PDF.