Status page best practices: what to publish, when, and how to stay honest

Start with the job the page has to do

A customer opens your status page for exactly one reason: something feels wrong on their end and they want to know if it's you or them, without waiting on a support reply. Every design decision on the page should be judged against that job. If a choice makes the page look better but makes that answer slower or less certain, it's the wrong choice.

That reframes a few common instincts. A status page is not the place for a changelog, a features roadmap, or upbeat copy about your uptime record. It is closer to a control room readout: current state first, evidence for that state second, history third.

What order things belong in

The reading order that gets a worried visitor to an answer fastest, in practice:

• Your name and the current overall state, labeled in words, not just a color.
• When that state was last confirmed, and from where.
• Per-component or per-region readings.
• Any active incident, with its most recent update first.
• Past incident history, for anyone checking whether a problem is recurring.

Burying the current state below a hero image or a pricing pitch defeats the page's only job. If someone has to scroll to find out whether you're up, the page has already failed the person who came to it during an outage, which is the only time most people visit it at all.

How granular your components should be

Granular enough that a customer can tell whether their specific problem is a known issue, not so granular that the page turns into an internal architecture diagram. “API”, “Dashboard”, and “Checkout” are components a customer recognizes and cares about individually. “us-east-1 RDS replica” is an implementation detail that belongs in your internal runbook, not a public component list, unless your customers are themselves infra engineers who specifically care about that layer.

If your service has genuinely independent regions, region-level state is a different, useful kind of granularity: it answers “is this affecting me specifically” for a geographically distributed customer base in a way a single global badge cannot. That's a different axis from component granularity, and the two are worth keeping separate on the page rather than merged into one confusing status grid.

When to post, and the discipline that makes it possible

Post the first update as soon as a real problem is confirmed, before customers have to ask. The practical way to hit that bar consistently is to let your monitoring open the first draft automatically the moment a check confirms a genuine state change, rather than waiting on a human to notice, decide it's worth a post, and then write one. A team that has to manually notice and manually decide to be transparent will, under pressure, sometimes decide not to, not out of bad faith but because someone is busy fighting the actual fire.

The full stage-by-stage cadence and templates for what to actually write during that window are covered in a companion guide below.

Staying honest when the truth is inconvenient

The hardest, most valuable discipline on a status page is refusing to make it say something better than what actually happened. Two specific failure modes are worth naming because they are common and easy to slide into without noticing:

• Resolved incidents that quietly disappear. If your page only shows currently active incidents and drops resolved ones from the visible history, a customer checking “did this happen to me last week too” finds nothing, even though it did happen. Keep resolved incidents visible in a history section. The instinct to hide old problems to look better is exactly backwards: a page with an honest incident history is more credible during your next outage than a page with a suspiciously spotless one.
• A badge that stays green because the check that would catch the problem doesn't exist. A single check from one location, run once a minute, only proves that one path works. It says nothing about a regional outage, a broken checkout flow the health check doesn't exercise, or degraded performance that hasn't crossed a hard failure threshold yet. Publishing a green badge is an implicit claim that you checked, and the claim is only honest if the check actually covers what it's claiming to represent. The mechanics of exactly how this goes wrong, and what checking from multiple regions fixes, are covered in the uptime monitoring guide.

Maintenance windows deserve their own treatment

Planned downtime is not an incident and shouldn't be dressed up as one, but it also shouldn't be invisible. Announce it in advance with a start and end time, keep it visible on the page during the window, and suppress the alerting that would otherwise fire your team a page for downtime you scheduled yourself. The goal is the same honesty standard as everything else on the page: a customer who checks during your maintenance window should immediately understand why things look different, without having to guess whether it's a real problem.