Status page best practices: what to show, what to leave out, and how to keep it honest

A status page is a promise to tell the truth quickly. What belongs on it, how to name components, why manual updates go stale, and what makes customers trust the page instead of checking Twitter.

Customers open a status page for one reason: something looks wrong and they want to know whether it is them or you. The page succeeds if it answers that in five seconds and is right. Everything else is secondary.

Show what customers can name

List the things a customer would recognise as a thing — *API*, *Dashboard*, *Checkout*, *Email delivery* — not your internal services. Nobody outside the company knows what orders-svc-eu-2 is. Five to ten components is typical; if you have forty, group them by product and show the groups.

Let monitoring drive it

The failure mode of most status pages is optimism: the incident is real, the page says operational, and it stays that way until someone remembers to update it. A page that is fed by the same monitors that page the on-call cannot lie by omission — the component goes degraded when the check fails, and recovers when it recovers. Keep the ability to post a human note, but do not make a human the only source of truth.

Show history, not only now

A 90-day uptime bar per component tells a prospective customer more than any SLA claim, and tells an existing customer that yesterday's blip was noticed. Show the percentage and the bar; the incident list under it is the receipt.

Handle maintenance as maintenance

Planned work should appear as scheduled maintenance ahead of time and as maintenance while it runs — never as an outage, and never as nothing. A maintenance window that suppresses alerts without telling customers is a quiet outage with a nicer name.

Keep it off your own infrastructure

If the page is served by the systems it reports on, it is down exactly when it is needed. Host it separately, on a subdomain (status.example.com) that is *not* behind the same CDN configuration, load balancer or DNS zone dependency as the product where you can avoid it.

Write incident updates like a person

• Investigating — what customers see, in their terms: "Some users cannot sign in." Not "elevated 5xx on auth."
• Identified — the cause in one sentence, and what you are doing.
• Monitoring — the fix is in; you are watching.
• Resolved — when it ended, and a link to a post-mortem if there will be one.

Post the first update within minutes even if it says only that you know. Silence for an hour costs more trust than the incident.