Scheduled maintenance announcements: warning users about planned downtime

Scheduled maintenance is the one change you announce before it happens — and the announcement carries almost all of the weight. Done well, users saved their work, API consumers paused their crons, and the window passed without a single ticket. Done badly, a planned, controlled, entirely successful maintenance window generates the exact same support storm as an outage — because from the outside, unannounced maintenance is an outage. The only difference between the two is whether the reader knew it was coming.

This guide covers when maintenance needs an announcement at all, the three-message rhythm that works, what the notice must contain, the timezone and duration honesty rules, what API consumers need that human users don’t, and the anti-patterns that turn a tidy planned window into a trust incident.

Does this maintenance need an announcement at all?

Announce by user-visible impact, not by how big the work feels from inside. A heroic all-night database migration that users never notice needs no announcement; a five-minute window where saves silently fail absolutely does. Three tiers:

  • Invisible maintenance — say nothing beforehand. Zero-downtime deploys, failovers users won’t feel, work behind the load balancer. Announcing these trains readers to ignore your maintenance notices — the operational version of crying wolf. If the work turns out to matter (performance was degraded after all), say so afterwards instead.
  • Degraded service — announce it plainly. Read-only mode, slower responses, a feature offline, delayed webhooks or exports. Name exactly what degrades and what keeps working; “some features may be affected” helps nobody decide anything.
  • Unavailable — announce it loudly, with lead time. Full downtime, login unavailable, API returning errors. This tier gets the full three-message treatment below, and lead time proportional to how badly a surprised user would be hurt.

Lead time scales with disruption and with who the reader is: a consumer app can announce a short window 2–3 days out; a tool people run their business on wants 1–2 weeks; and if enterprise admins are affected, contracts often specify 30 days — check before you book the window, not after.

The three-message rhythm

One announcement is not enough, and five are too many. The pattern that works is advance notice → starting now → all-clear:

  • Advance notice — the full announcement, published with the lead time above, in the channels people already watch: the status page as the authoritative copy, mirrored as an announcement-tagged changelog entry so feed and widget subscribers hear on their own clock, and email only when the reader must actually do something (or is contractually owed notice). For windows announced far ahead, one reminder a day or two out is a courtesy; more is noise.
  • Starting now — a one-liner when the window opens, on the status page. It converts “is it down?” into “ah, right, the maintenance” for everyone who missed the advance notice — and someone always misses the advance notice.
  • All-clear — when service is restored, say so, with the actual end time. If the window closed early, this is a pleasant surprise; if you skip the all-clear, every user who was waiting keeps waiting.

The live half of this rhythm belongs to the status page — that is its job. The changelog’s job is the scheduled advance notice and the durable record; keep the division and neither channel has to pretend to be the other.

What the announcement must contain

Five things, in roughly this order:

  • The window, unambiguously. Date, start, end, timezone — see the next section, because this is where most notices fail.
  • What will actually be unavailable — and what won’t. Use the names readers see in your UI, not your architecture (their labels, not your internals). “The dashboard stays up; publishing and imports are paused” lets a reader plan. “Some services will be undergoing maintenance” is a shrug in prose.
  • What the reader should do. Save work before the window, avoid scheduling deploys across it, expect queued webhooks to arrive late. If the answer is genuinely “nothing,” say that — it is the single most calming sentence a maintenance notice can contain.
  • One line of why. “We’re upgrading the primary database” is plenty. It reads as a team doing deliberate work rather than a mysterious interruption — but keep it to a line; the notice is not the venue for infrastructure show-and-tell.
  • Where live updates will appear. Link the status page. During the window, that link is the answer to every “how much longer?”

Writing the window: timezone and duration honesty

Two rules cover most of the failure modes:

Write times a stranger can’t misread. State the timezone explicitly, prefer UTC as the canonical time with a local-time hint if your users cluster somewhere (“02:00–04:00 UTC — that’s 9–11 PM Tuesday US Eastern”), and never use bare abbreviations like “EST” — half the year it’s wrong, and your readers shouldn’t need to know which half. Dates follow the same unambiguous-format rule as changelog dates: 2026-08-04, not 04/08.

Announce the window you booked, not the duration you hope for. If the migration should take 40 minutes but you booked two hours, announce two hours. Finishing early is a pleasant surprise; running past the announced end is indistinguishable from an incident — because at that point it is one. Which yields the overrun protocol: the moment you know you won’t make the window, post an update with a new estimate. Silence past the announced end time converts every goodwill minute the advance notice bought into doubled distrust.

API consumers are a separate audience

A human sees a maintenance banner and comes back later. A script sees errors and does whatever it was programmed to do — which, if its authors never heard about the window, may be “retry in a tight loop” or “page the on-call.” If you have an API, the notice needs an integrations paragraph (the API changelog discipline applies):

  • What the API will return during the window — ideally 503 with a Retry-After header, stated in the notice so consumers can handle it deliberately rather than discover it.
  • Whether writes are queued or refused. “Requests during the window fail and should be retried after” and “webhooks are queued and delivered late” are different integration plans. Say which one is true, per surface.
  • What their alarms will see — monitoring-minded consumers will silence their own alerts for the window, but only if they know when it is. This is exactly the reader who subscribes to your feed with a script: give the notice a stable permalink and an ISO-dated window so their tooling can act on it.

Recurring windows: publish the policy once

If you maintain regularly, a standing window — “Sundays 02:00–04:00 UTC, used roughly monthly” — moves most of the ceremony into a policy page readers see once, the same move as publishing a deprecation policy. Individual routine windows then need only a short notice referencing it. Two honesty rules keep the policy meaningful: announce loudly anyway when a particular window will hurt more than usual (longer, or fully down instead of degraded), and don’t hold a standing window you rarely use — a reservation that never fires teaches readers the notices are boilerplate.

A template

Scheduled maintenance: database upgrade — 2026-08-04

When: 2026-08-04, 02:00–04:00 UTC (9–11 PM Aug 3, US Eastern)
What’s affected: the app is read-only — browsing works, saves and
imports are paused. The public API returns 503 with Retry-After.
What to do: nothing is lost; anything you submit after the window
behaves normally. Pause scheduled jobs that write during the window.
Why: we’re upgrading the primary database to faster hardware.
Live updates: status.example.com

We’ll post an all-clear here and on the status page when it’s done.

Every line answers a reader question; delete none of them, and resist adding more — a maintenance notice is read in ten seconds by someone mid-task.

Anti-patterns

  • “Brief scheduled maintenance” with no window. No start, no end, no timezone — the reader can plan nothing, which was the entire point of announcing.
  • Announcing after starting. A notice posted ten minutes into the window is an outage confession wearing a maintenance costume. If the advance notice didn’t happen, treat it as an incident and communicate like one.
  • Social-only announcements. A post on X/Bluesky reaches whoever happened to scroll past. The notice belongs where users already look: status page, changelog feed, in-product.
  • Overrunning silently. The announced end passes, service is still down, the status page still says “scheduled maintenance.” Update with a new estimate the moment the old one dies.
  • “To serve you better.” Marketing varnish on a downtime notice reads as evasion. Plain operational voice: what, when, what to do.
  • Announcing everything. Ten notices a month for invisible work means the eleventh — the one that matters — gets skimmed past. Announce impact, not effort.

Doing this with Wakelog

Wakelog handles the changelog half of maintenance communication. Write the advance notice as an announcement-tagged entry; with scheduled publishing (publish_at) you can write it today and have the reminder land two days before the window on its own. Every entry gets a stable permalink — the URL your support team pastes into tickets and your API consumers’ tooling can watch via the RSS/JSON feeds — and per-project Discord/Slack webhooks mirror the notice where your community actually reads. Honest caveat: Wakelog is not a status page — there are no live incident updates or uptime graphs, and the “starting now” / overrun messages belong on one. Pair it with a status tool and keep each channel doing its own job.

Schedule your next maintenance notice   Next: status page vs changelog →

Related guides

  • Status page vs changelog: what each one is for
    "Is it up?" and "what changed?" are different questions. When you need a status page, why merging the two backfires, and the incident → changelog loop.
  • IT change communication: announcing system changes to your employees
    The second-hand changelog: announcing changes to software you didn’t build, to readers who never chose it. Employees can’t churn — the cost of bad change comms is ticket spikes, shadow IT, and announcements nobody reads anymore.
  • Incident postmortems vs changelog: what to publish after things break
    The status page says “we noticed,” the changelog says “we fixed it,” and the postmortem says “here is what actually happened and what changes.” When an incident earns a public postmortem, the anatomy of one worth reading, and the follow-through loop almost nobody closes — tracking the promised fixes back through the changelog.

Last updated 2026-07-31 · All guides