internal-comms

Internal Communications

Internal comms fail in two ways: too long (nobody reads them) or too vague (nobody acts on them). The goal is a message that gets read, understood, and acted upon — by the right people, in the right amount of time.

Write for the reader's context, not your own. The reader is busy, has incomplete context, and will skim before they read. Lead with the conclusion.

---

Internal Comms Principles

• Lead with the bottom line. The most important thing goes first. Background and rationale come after. Executives and busy engineers read the first paragraph and stop.
• One message, one action. Every communication has exactly one thing it wants the reader to do: approve, acknowledge, unblock, attend, or stay informed. Name it explicitly.
• Shorter is always harder to write and easier to read. Spend the extra time to cut.
• Tone matches urgency and audience. A P0 incident update is clinical and fast. A team launch announcement is warm and energetic. Read the room.
• Never bury the ask. If you need something from the reader, state it in the first 2 sentences or in a clearly labeled "Action Required" section.
• Facts over feelings in incident reports. What happened, what broke, what was the impact, what we did, what we're doing to prevent recurrence. No blame. No speculation.

---

Communication Types

1. Incident Report / Post-Mortem

Use when: a production incident, outage, data issue, or security event occurred and needs to be documented.

Format:

## Incident Report — [Service/Feature] — [Date]

**Severity:** P0 / P1 / P2
**Status:** Resolved / Ongoing / Monitoring
**Duration:** [start time] → [end time] ([X hours Y minutes])
**Impact:** [Who was affected, how many users, what they couldn't do]

---

### Timeline
| Time (UTC) | Event |
|---|---|
| HH:MM | Monitoring alert fired for [metric] |
| HH:MM | On-call engineer paged |
| HH:MM | Root cause identified: [one sentence] |
| HH:MM | Fix deployed to production |
| HH:MM | Service confirmed healthy |

### Root Cause
[One paragraph. What broke, why it broke, what conditions triggered it.]

### Impact
- **Users affected:** [number or percentage]
- **Duration of impact:** [X hours Y minutes]
- **Services affected:** [list]
- **Data loss:** [Yes/No — if yes, describe]

### What We Did
[Ordered list of actions taken during the incident]

### Action Items
| Action | Owner | Due Date | Status |
|---|---|---|---|
| [Prevent recurrence action] | @engineer | YYYY-MM-DD | Open |
| [Monitoring improvement] | @engineer | YYYY-MM-DD | Open |

### What Went Well
- [Something the team handled well]

### What Could Be Improved
- [Process or system gap revealed by this incident]