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

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 is a writing tool. Rollback is an operations tool that documentation borrowed from deployment, and it is the one missing from most docs platforms.

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.

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.

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.

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.

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.