If Publishing Is Hard, Your Docs Go Stale

I kept a knowledge base that was genuinely useful and perpetually a little out of date, and for a long time I blamed myself — not disciplined enough, not diligent about publishing. The real culprit was friction. Updating the live site meant remembering a manual sequence of steps, so I did it in batches, late, and sometimes not at all. When I finally automated it — write, commit, push, and the published site updates itself within seconds — the staleness problem evaporated. Not because I got more disciplined, but because the gap between writing and publishing closed, and docs rot in exact proportion to the size of that gap.

Friction is the real reason docs go stale

The standard explanation for stale documentation is a people problem: nobody bothers to keep it current. I think that’s mostly wrong. People don’t update docs because updating them costs something — a separate publish step, a manual build, a deploy ritual, a context switch away from the work. Every unit of that cost is a reason to defer, and deferred-forever is how docs die. The staleness isn’t a character flaw; it’s a rational response to friction. Raise the cost of publishing and you lower the rate of publishing, every time.

Documentation doesn’t rot because people are lazy. It rots because publishing it costs more than skipping it.

Make publishing a side effect, not a task

The fix is to make publishing not a separate thing you do. In my case, the authoritative source is a set of plain markdown notes in version control. So I wired a pipeline: a push to the main branch automatically syncs the notes flagged for publication, builds the site, and pushes the result into the running server. The publish step disappeared into the act of saving my work. I no longer “publish the docs” — I just write, and the published version follows. When updating the live site is a side effect of the normal workflow rather than an extra chore, currency stops depending on willpower.

That’s the whole move: turn publishing from an action someone has to take into a consequence of work they were already doing. The most reliable way to make a step happen consistently is to make it happen automatically.

Automate the path, but keep the gate

“Automatic” doesn’t mean “everything, indiscriminately.” My notes are private by default; only the ones explicitly flagged for publication get synced to the public site. So the pipeline is automatic but curated — the automation handles the mechanics of publishing, while a deliberate flag controls what gets published. That separation matters: you want zero friction on the act of publishing and a clear, intentional decision about what’s ready to be seen. Automating the plumbing doesn’t mean surrendering editorial control; it means you spend your judgment on “should this be public?” instead of on “how do I get it there?”

Lower the friction even when it fights you

Building the pipeline meant pushing through a string of environment gotchas — the kinds of things that work on your laptop and break in automation. It would have been easy to give up and keep publishing by hand. But that effort is a one-time cost that buys a permanent drop in per-update friction, and that’s the trade that pays off. Spending a day to make every future publish free is almost always worth it, because the alternative is paying a small friction tax forever and watching the docs gradually fall out of sync with reality. Invest once in the plumbing; collect the dividend on every update after.

The principle generalizes to anything you want done often

This isn’t really about docs — it’s about any good practice you want to happen consistently. The reliable way to get something done routinely is to make doing it cheaper than skipping it, ideally automatic. Tests that run on every commit. Formatting applied on save. Backups on a timer. Publishing on push. Each is the same insight: don’t rely on humans to repeatedly choose the virtuous-but-annoying option — remove the friction so the virtuous option is the path of least resistance. It pairs with treating documentation as infrastructure and with the broader habit of building a knowledge system that compounds instead of decays. If you’ve killed a stale-docs problem by automating the publish path, I’d like to hear how you wired it.