Good technical work that isn't communicated well might as well not have happened — stakeholders can't trust what they can't see. This section covers how to communicate updates about platform changes, maintenance, incidents, and ongoing projects, plus a reusable template.

Why this matters more than it seems¶

In platform/infra roles, you're often invisible when things work and highly visible when they don't. Deliberate communication:

• Builds trust — stakeholders stop needing to ask "is this still happening?"
• Reduces interruptions — a well-timed update pre-empts five Slack DMs
• Creates a paper trail — useful for postmortems, audits, and your own performance record
• Manages expectations — nobody is surprised by downtime, delays, or scope changes
• Protects you — a documented update is evidence you communicated proactively, not just reactively

Know your audience before you write¶

The same change needs different framing depending on who's reading:

A common failure mode is writing one message and blasting it everywhere. A short exec-friendly summary plus a linked detailed doc usually serves both audiences better than one message trying to do both jobs.

The core update types¶

• Pre-change notifications (planned work) — sent before a change: maintenance windows, migrations, upgrades, deprecations.
• In-progress status updates — sent during longer-running work or incidents: "still investigating," "rollout at 40%."
• Completion / post-change summaries — sent after the work: confirms success, notes any deviations, closes the loop.
• Incident communications — a specialized case of in-progress updates: time-sensitive, higher-anxiety audience, needs a more frequent cadence even when there's "nothing new" to say.
• Retrospective / postmortem summaries — sent after the dust settles: root cause, impact, follow-up actions. Blameless, factual, forward-looking.

Each has different timing and tone expectations, covered below.

Timing guidelines¶

Silence is the enemy in an active incident — people assume the worst when updates stop, not when problems appear.

Anatomy of a good update¶

Regardless of type, a strong update usually answers, in order:

1. What is happening (one sentence, plain language)
2. Who/what is affected (be specific — service names, teams, regions, not "some systems")
3. When (start time, expected duration, timezone — always state the timezone)
4. Impact (what will users actually notice, if anything)
5. Action needed from the reader (often "none," but say so explicitly — ambiguity breeds anxiety)
6. Where to go for more info / status (link to status page, channel, ticket)
7. Who to contact (a name or team, not just "reach out with questions")

Cut anything that doesn't serve one of these seven purposes. Padding a maintenance notice with implementation detail nobody asked for buries the parts people actually need.

Tone and language principles¶

• Lead with impact, not mechanism. "The billing API will be unavailable for 10 minutes" beats "We are performing a rolling restart of the payment microservice cluster."
• Avoid hedging language in confirmations. "This should be fixed" reads as uncertain. If it's fixed, say "This is fixed." If you're not sure, say "We believe this is resolved and are monitoring."
• Use active voice and concrete numbers. "Expect ~5 minutes of downtime starting at 2:00 PM ET" beats "There may be some brief disruption."
• Don't bury the lede in acronyms. Define or avoid internal jargon for cross-functional audiences.
• Say "no impact expected" explicitly when true. Readers assume risk unless told otherwise.
• Own mistakes plainly. "We misjudged the migration window" is more trust-building than vague language that avoids responsibility.
• Match urgency to reality. Don't cry wolf with "CRITICAL" banners on routine patches — it erodes signal for when something really is critical.

Channels: match the medium to the message¶

Rule of thumb: ephemeral channels for ephemeral updates, durable channels for anything someone might need to find in six months.

Common pitfalls¶

• Announcing "done" before verifying. Confirm success before declaring completion — a retracted "all clear" costs more trust than a slightly later one.
• Over-notifying. Sending every micro-step to a broad audience trains people to ignore your updates. Reserve broad channels for milestones.
• Under-notifying during incidents. "No update" is still an update — send it anyway on cadence.
• Assuming context. Not everyone remembers the original announcement — briefly restate what's happening in follow-ups.
• No rollback/contingency mention. For risky changes, stating the rollback plan reassures technical stakeholders even if it's never invoked.
• Passive voice hiding accountability. "Mistakes were made" vs. "We made a mistake in the deployment order."
• Forgetting the timezone. Always state it explicitly, especially with distributed teams.

Template¶

A flexible template — adapt sections to the update type and audience. Sections marked (optional) can be dropped for lower-stakes updates.

Subject: [STATUS] <Short, specific description> — <Date/Time>

Summary
-------
<One or two sentences: what's happening and why. Plain language.>

Affected
--------
Systems/Services: <specific names>
Users/Teams: <who is impacted — be specific>
Regions/Environments: <if applicable>

Schedule
--------
Start: <date, time, timezone>
Expected duration: <estimate>
End (or expected end): <date, time, timezone>

Impact
------
<What will people actually notice? If none expected, say so explicitly:
"No downtime or user-facing impact is expected.">

Action Needed
-------------
<What, if anything, does the reader need to do? Default to "No action needed."
If action is needed, be specific: what, by when, how.>

Rollback / Contingency (optional)
----------------------------------
<Brief note on what happens if something goes wrong, and how it will be
communicated.>

Status Updates
--------------
<Where to check for live status — link to status page, channel, or ticket.>
Next update: <time, or "at completion / if status changes">

Contact
-------
<Name/team + how to reach them for questions or escalation>

---
Related ticket/change record: <link>

Example — filled in (routine maintenance)¶

Subject: [MAINTENANCE] Elasticsearch cluster upgrade — Aug 24, 2026

Summary
-------
We are upgrading the logging cluster to the latest patch version to
address a known indexing performance issue.

Affected
--------
Systems/Services: Central logging / Kibana dashboards
Users/Teams: Platform, SRE, anyone using Kibana for log search
Regions/Environments: Production

Schedule
--------
Start: Aug 24, 2026, 9:00 PM ET
Expected duration: ~45 minutes
End: ~9:45 PM ET

Impact
------
Kibana dashboards will be read-only during the upgrade window. Log
ingestion continues normally and no data will be lost; there will be a
brief indexing delay of a few minutes after the window closes.

Action Needed
-------------
No action needed. If you have a saved Kibana session open, expect to
need to refresh after 9:45 PM ET.

Rollback / Contingency
-----------------------
If the upgrade fails validation, we will roll back to the prior version
within the same window. An additional update will be sent if this occurs.

Status Updates
--------------
Live status: #platform-status Slack channel
Next update: at completion, or immediately if any issue arises

Contact
-------
<Your name> — Platform/DevOps — reachable in #platform-status or via
[ticket link]

---
Related ticket: PLAT-1234

Checklist before you hit send¶

• [ ] Audience identified and message tailored to them
• [ ] What, who, when, impact, and action are all explicit
• [ ] Timezone stated
• [ ] "No action needed" stated explicitly if true
• [ ] Right channel(s) for the audience and durability needed
• [ ] Link to live status / ticket included
• [ ] Contact name or team included
• [ ] Tone matches actual severity — not inflated, not underplayed
• [ ] If this is a completion notice: have you actually verified success?