Consider two alerts for the same problem. "ALERT: rule_id 4471 threshold exceeded on prod-cluster-2" versus "Check 'Payments API' is DOWN — HTTP 503 for 4 min. Started 03:12. Runbook: link." Both detected the failure. Only one lets a person who was asleep ninety seconds ago start doing something.
The four things every alert needs
What is broken, in the language humans use — not an internal identifier. How bad it is, with a hint of blast radius. When it started, as a duration rather than a timestamp. Where to go next — a link to the incident and ideally a runbook.
What to leave out
Stack traces, which belong in the incident record. Raw metric dumps. Anything requiring interpretation — say "error rate 4.3%, normally under 0.5%" rather than "error_rate: 0.043." Uppercase panic.
A template
[SEVERITY] <Service> — <what is wrong>
<evidence>
Started <duration> ago
<link>
Under two hundred characters, survives SMS truncation, and answers every question a responder has in the first thirty seconds.
Severity that means something
Severity is only useful if the levels map to distinct responses. Note that most systems auto-creating incidents assign one default severity regardless of what failed, so tune the ones that matter by hand or route by source.
Runbook links are the highest-leverage field
A runbook needs to answer three questions: is this actually a problem or a known benign cause, what are the first three things to check, and who to escalate to. Ten lines is enough, and you should write it during the incident while the knowledge is fresh.
Channel-specific shaping
SMS and voice get one sentence. Chat and email can carry the full context. If your tooling sends the same body everywhere, the SMS is the constraint — write for that.
The feedback loop
After each page, ask: did the alert tell you what you needed? If not, fix it immediately while the memory is sharp. Alerts written this way converge on something genuinely good within a few months; alerts written once during setup stay bad indefinitely.