# Rollback for documentation, and why version history isn’t it

Version history restores a file. Rollback restores the site your readers are looking at. The difference matters at the exact moment you need it, which is usually ten minutes after a publish went out with something wrong in it.

_Source: https://docszero.com/resources/documentation-rollback_
_explainer · 6 min read_
_Published 10 September 2026_

> **In short:** Keep both. Version history is for the writer who wants a paragraph back. Rollback is for the moment the published site is wrong and every minute counts — and it should be a pointer move to output you already built, not a rebuild you have to hope succeeds.

## Two different things with similar names

Most documentation tools have version history. Far fewer have rollback, and the two get talked about as if they were the same feature.

|   | Version history | Rollback |
| --- | --- | --- |
| Restores | A page, to an earlier draft | The whole published site |
| Scope | One file | Everything that went out together |
| Used by | A writer, while writing | Anyone, when the site is wrong |
| Typical trigger | “I preferred the old wording” | “The install guide is broken” |
| Time pressure | None | All of it |

Version history is a writing tool. Rollback is an operations tool that documentation borrowed from deployment, and it is the one missing from most docs platforms.

## Why documentation needs it at all

The objection is reasonable: it is only documentation, so how bad can a wrong publish be. Then you look at what a docs site is actually load-bearing for.

- An install guide with a wrong command, on the day of a launch, in front of everyone who just heard about you.
- A migration page where a find-and-replace ran one field too far and every code sample is now subtly wrong.
- A restructure that renamed twenty pages, broke every deep link support has ever sent, and did it at 5pm.
- A security note published before the fix shipped.
- A whole section accidentally deleted and published by someone who did not realise Publish sends everything.

In each of these the question is identical and it is not "what did the page say last week". It is: **how fast can the site go back to how it was an hour ago**. Version history answers a different question, one page at a time, while a customer is reading the wrong one.

## How rollback should work

There is a good design for this and the industry settled on it years ago for application deployment. Documentation should simply use it.

### Never overwrite output

Every build writes its own output and keeps it. Publishing is not "replace the files"; it is "point the site at build 47". Nothing is destroyed by a later publish, so nothing has to be recovered.

### Rolling back is moving the pointer

Because build 46 still exists exactly as it was served, going back to it is a pointer move rather than a rebuild. It takes effect at once, and it cannot fail for a reason that has nothing to do with your content — a dependency that moved, a service that is down, a runner with no capacity.

> This is the property that matters and it is easy to miss. A rollback implemented as "check out the old commit and build it again" is a rollback that depends on a build succeeding, at the exact moment you have proven something is going wrong. The whole point is not to need luck.

### A failed build never replaces what is live

The other half of the same idea. If a build fails, the previous one stays published and the failure is shown to the person who caused it, with the log. Readers see the last good site throughout. Rollback is for content that built fine and was wrong; this is for content that never built at all.

### The look rolls back too

A detail almost everyone forgets: if your platform lets you change themes, colours or a logo, those are part of what was published. A rollback that restores last week’s words under this morning’s half-finished brand colour has not restored anything. Every publish should remember the look it went out with.

## “We use Git, we already have this”

Partly true, and worth being precise about, because a repository gives you history but not necessarily a way back.

Git gives you a perfect record of what the source said. What it does not give you is the built site from that moment. To get back you revert the commit, push, and wait for CI to build and deploy — which is a rebuild, under time pressure, with all the ways a rebuild can fail still available to it. If the pipeline is what broke, revert does not help at all.

|   | Git revert and rebuild | Pointer to a kept build |
| --- | --- | --- |
| Time to live | However long CI takes | Immediate |
| Can it fail? | Yes, anywhere in the pipeline | No build runs |
| Needs the pipeline healthy | Yes | No |
| Needs a person who can push | Usually | Anyone with access |
| Restores the exact bytes served | Only if the build is reproducible | Yes, by definition |

If your CI is fast and reliable, revert-and-rebuild is a perfectly good answer and you should not add machinery to replace it. The gap shows up on the bad day, which is the only day this feature is for.

## What this looks like in Docszero

Both layers exist, and they are deliberately separate because they answer the two different questions above.

- Every save is a version of that page you can restore, while you are writing.
- Every build is kept — first build, publishes and rebuilds, all listed newest first with what caused each one and how long it took.
- Output is never overwritten, so rolling back is a pointer move and it is live at once.
- Roll back from the row itself; there is nothing to check out and nothing to rebuild.
- A failed build never replaces the live site, and shows you the log with a hint in plain words.
- Every publish remembers its look, so a rollback restores the theme, brand colour and logo that went out with it.

Drafts are the piece in front of all of this: saves land on a private draft and the published site does not change until you press Publish. Most of the incidents in this article are prevented there rather than recovered from — but the recovery exists, because eventually one of them is not.

## Questions

### What is the difference between version history and rollback?

Version history restores a single page to an earlier draft and is a writing tool. Rollback restores the entire published site to an earlier build and is an operations tool. You want both: one for “I preferred the old wording”, the other for “the install guide is wrong and customers are reading it now”.

### How fast should a docs rollback be?

Immediate, which means it cannot involve a build. If every build keeps its own output, going back is a matter of pointing the site at an earlier one, so it takes effect at once and cannot fail for reasons unrelated to your content. A rollback that rebuilds is a rollback that needs the pipeline to be healthy at the exact moment something has already gone wrong.

### Isn’t Git enough for documentation rollback?

Git records what the source said, perfectly. Getting back to a published state still means reverting, pushing and waiting for CI to rebuild and deploy — and if the pipeline is what broke, that path is closed. If your CI is fast and reliable this is fine; the gap only appears on the bad day, which is the day the feature exists for.

### What happens to my docs site if a build fails?

Nothing, for your readers. The previous build stays published and the failure is shown to you with the log and a plain-language hint. Warnings such as a broken internal link do not fail a build, so a small mistake still publishes rather than blocking everything behind it.

### Does rolling back also restore the theme and logo?

In Docszero, yes. Every publish records the appearance it went out with — theme, brand colour and logo — so rolling back to an earlier build brings back the look as well as the words. A rollback that restored old text under a new half-finished brand colour would not have restored the page anyone actually saw.

---

Published by Docszero (https://docszero.com) — docs, minus the setup. Upload Markdown, a Word document or a PDF and get a searchable documentation site. Free for one site; export the source on every plan.