An incident page should help customers decide what to do while the service is disrupted. A generic “we are investigating” message is incomplete when users need to know whether to retry, wait, or preserve an unsaved draft.
Write the page around affected workflows and known facts. Keep diagnosis, speculation, and private customer details out of the public update unless they are necessary and authorised.
State impact before internal causes
Name the affected function, the observed behaviour, when the issue began or was detected, and which users or regions are known to be affected. Distinguish confirmed scope from ongoing investigation.
Provide a safe next action. If retrying can duplicate work, say whether users should wait. If a draft remains unsaved, explain how to preserve it under the product's supported workflow. Avoid promising recovery of data that has not been verified.
Draft a fictional response-submission incident
Suppose some study participants receive an error after submitting feedback. The team has confirmed delayed confirmation but has not yet established whether every response was stored.
A useful initial update states that submission confirmation is affected, names the known time window, explains the current retry guidance, and gives the next update time. It does not announce data loss or assure complete preservation without evidence.
As investigation progresses, update the scope and action guidance. When service recovers, verify fresh submissions and the status of affected earlier attempts before marking the incident resolved. A provider's recovery announcement alone does not prove the application's backlog is reconciled.
Define publication ownership before an outage
Name who can post updates, who verifies technical claims, and which route remains available if the main application is down. Keep access recoverable so a single unavailable founder does not prevent communication.
Separate public updates from private support cases. A customer-specific record reference, email address, or response content does not belong on a shared incident page. Give affected customers an appropriate private contact path.
The tradeoff is speed versus certainty. An early bounded update can be useful without a confirmed root cause. Overly detailed speculation can mislead users and require repeated corrections. State what is known, what is being checked, and when the next update will arrive.
Afterward, record the cause, impact, recovery steps, and follow-up work at a level appropriate to the audience. The purpose is to make future decisions and response better, not to manufacture a dramatic story.
The StackFlight case study supplies study-workflow context. This incident is fictional and does not describe an outage or measured reliability result for that product.
Questions about incident pages
Should the page include the suspected root cause?
Only if it is useful and clearly identified as unconfirmed. Customer impact and safe actions usually matter first.
Is provider recovery enough to resolve the incident?
No. Verify your application's workflow, queued work, and affected records before declaring the customer impact ended.
What should be tested before launch?
Rehearse posting an update while the main app is unavailable and verify access, ownership, and customer guidance. Bring gaps to an operations review.