How to Communicate an Unplanned Downtime in Your Release Notes

If you run a software team long enough, eventually you will have a bad Tuesday.

Maybe AWS decided to reboot a few of your servers for a critical update, taking out a secondary replica of your database. Maybe the driver handled that poorly and spent the first 400ms of every subsequent request trying to reconnect. Maybe that server came back up but failed to find its storage volumes because of a human mistake in a past migration.

Whatever the sequence of events, the site went down. Your team spent four hours fighting the fire. The fix is deployed. The metrics are stable. The incident response channel has gone quiet. The engineers are finally getting some sleep.

Now someone has to figure out what to say about it.

The immediate crisis is over, but the secondary problem is just beginning. You have a scheduled release note going out on Thursday. The product manager wants to highlight the new dashboard filtering features. The support lead wants to apologize profusely for the outage. The engineering manager wants to explain exactly how the connection pool exhaustion happened. The executive team would prefer everyone just focus on the new features and forget the database ever went down.

This is the tension of incident communication. When unplanned downtime happens, it forces a decision about transparency. You have to decide whether to acknowledge the failure in your regular release notes, how much detail to provide, and how to frame the event so that users maintain their trust in your system.

The Part Everyone Gets Wrong

Not every incident belongs in a release note.

If a deployment fails in staging and never reaches production, the user never saw it. There is no trust to repair because no trust was broken. If a background job processing analytics data gets delayed by two hours but recovers automatically without affecting the user interface, mentioning it might cause more confusion than clarity.

The decision to acknowledge downtime rests on three factors.

First, visibility. Did users notice the outage independently, or would they only know about it if you told them? If users saw error pages, filed support tickets, or complained on social media, the incident is public. You cannot ignore it. Silence in the face of a visible failure signals either incompetence or dishonesty.

Second, severity. How many users were affected, and for how long? A three-minute blip that affected a fraction of traffic might warrant a brief mention. A four-hour outage that prevented users from completing core tasks requires a dedicated explanation. If data was lost or corrupted, the communication priority supersedes everything else.

Third, recurrence risk. Was this a one-time infrastructure anomaly, or is it a symptom of a systemic issue that might happen again? If the root cause is complex and requires long-term architectural changes to fully resolve, users need to know that you are aware of the underlying fragility and are actively working on it.

When to Stay Quiet

There are times when a release note is the wrong vehicle for incident communication.

If you have already published a detailed, public incident report or post-mortem on your status page or engineering blog, rehashing the entire event in a release note is redundant. In this case, the release note should simply link to the full report. Cloudflare's detailed breakdown of their November 2025 outage, for example, lived on their engineering blog, not buried in a routine product update.

If the incident happened weeks ago and users have stopped asking about it, bringing it up again in a routine release note might reopen a closed wound. The rule of thumb here is simple. If support is still fielding questions about the outage, address it. If the user base has moved on, you probably should too.

Release notes are also the wrong place for internal politics. They are not the venue to explain that the outage happened because the platform team refused to prioritize the database migration. They are not the place to blame a specific vendor. They are certainly not the place to blame a specific engineer.

How to Actually Write It

When you do decide to include downtime in a release note, the structure matters as much as the content. The goal is to provide enough technical detail to show that you understand the problem, without requiring the reader to have a computer science degree to parse the explanation.

Lead with what happened and when. Do not bury the lede. One clear sentence is enough. "On Tuesday afternoon, a subset of users experienced errors when trying to load the main dashboard."

State the impact scope. Be specific. "This affected approximately fifteen percent of active sessions between 2:00 PM and 4:15 PM EST."

Explain the root cause at the right level of abstraction. You do not need to paste the stack trace. You do need to explain the mechanism of failure. "A routine update to our database configuration caused the connection pool to exhaust its available slots, preventing new requests from completing."

Describe what you did to resolve it. "We rolled back the configuration change and manually restarted the affected database nodes to clear the connection queue."

State what you are changing to prevent recurrence. This is the most important part. "We have updated our deployment pipeline to run connection load tests against configuration changes in staging before they reach production."

Look at how GitHub handled their January 2016 power outage. They clearly stated the impact ("Slightly over 25% of our servers and several network devices rebooted"), the root cause (a firmware issue causing servers to not recognize their drives after power-cycling), and the mitigation (updating firmware across the fleet). It was factual, accountable, and forward-looking.

The Anxiety of Leadership

Sometimes leadership wants to bury the incident. They worry that talking about failure makes the company look weak.

This is a fundamental misunderstanding of how trust works in software. Trust is not built by pretending failures never happen. Every user knows that software breaks. Trust is built by demonstrating that when failures do happen, the team is capable of diagnosing the root cause and implementing a durable fix.

Atlassian's incident communication guidelines put it plainly: "some of your customers may worry you have more bad experiences up your sleeves and switch to a competitor. You'll lose future customers due to lack of trust." The inverse is also true. Teams that communicate clearly during incidents, even when the news is bad, tend to retain users who would otherwise quietly churn.

The tension between burying the incident and over-apologizing is real. Support teams, who bear the brunt of user frustration, often want to lead with a massive apology. Engineering teams often want to lead with a technical defense.

The framework for navigating this tension is to focus on the operational reality. Acknowledge the failure. Explain the fix. Commit to the improvement. Apologize once, sincerely, and move on.

What Machines Cannot Do

Automated release note systems can handle the scaffolding of documentation. They can pull commit messages, summarize feature branches, track dependency updates, and format the version history.

But communicating unplanned downtime requires a human decision.

An automated system cannot decide whether an internal database blip warrants a public apology. It cannot navigate the political tension between the product manager's desire to highlight new features and the support lead's need to address user frustration. It cannot choose the exact level of technical abstraction required to explain a connection pool failure to a non-technical user.

Doc Holiday is built for this reality. It generates the technical foundation of your release notes directly from your engineering workflows, pulling the facts together so you do not have to hunt for them. But it leaves the framing, the tone, and the strategic decisions to the humans who understand the context. It handles the scale and the consistency, giving your team the space to decide exactly what story to tell about the incident.