The Incident That Taught Me How to Communicate

I used to think that knowing the technical details was enough. I was wrong. More than once, I found myself explaining something only to realize that no one really understood what I meant. Whether it was a missed deadline, confused teammates or frustrated stakeholders. The problem wasn’t the work itself, it was how I communicated it.

At some point, my psychologist told me something that stuck with me: I am responsible for ensuring that what I communicate is received exactly as I intend it, to be clear, concise and without room for ambiguity. If there is a misunderstanding it is not just because the other person didn’t get it, but because I didn’t explain it well enough. This realization changed the way I approach communication, especially in high stakes situations where precision is everything.

One of the most painful lessons in communication happened while I was working for a large insurance company based in the United States. At the time, my role was more focused on cloud infrastructure than actual development, which meant I was responsible for ensuring that our services were running smoothly in AWS.

It all started with an outage that, at first, made no sense. Multiple internal and external APIs started failing simultaneously, causing a domino effect across different services. At first we assumed it was a connectivity issue, or possibly that one of our RDS instances was failing, but after checking the CloudWatch logs, there was nothing indicating a problem with the database. The metrics looked normal, no spikes in latency, no unusual CPU usage. That meant the issue had to be somewhere else.

As we dug deeper, we found something unexpected: our DNS configuration had completely disappeared.

For some reason, still unclear at that moment, our Route 53 DNS records had been wiped out, leaving all our domain mappings broken. This meant that not only were our APIs inaccessible but any external service relying on them was also failing. The only way to fix it was to manually recreate the DNS configuration, update all records and propagate the changes across AWS, which resulted in a total downtime of about 45 minutes.

After investigating further, we discovered that the root cause was a misconfigured CloudFormation deployment. Someone had executed a CloudFormation stack update, but instead of modifying the existing records, it rolled back to an outdated state where the DNS settings were missing. Since the deployment was automated, the rollback happened without immediate visibility, and by the time we realized what had happened, the damage was already done.

That was the technical side. Now here’s where things got tricky.

---

The War Room and the Communication Breakdown

Since we were the owners of the product and service we had to jump into a war room call with both our engineering team and business stakeholders to explain what had happened. There was a dedicated cloud engineering team, but since we owned the service, it was our responsibility to articulate the issue clearly.

The problem? The audience was a mix of engineers, managers and executives, each with different levels of technical understanding. I remember trying to explain it the way I understood it:

“The DNS records were deleted, so our services couldn’t resolve domain names, which caused failures across our APIs”

To me, this was straightforward. To everyone else, it wasn’t.

• Cloud engineers understood but wanted more details. How did it happen? Was it a misconfiguration or an AWS issue?
• Developers were confused. What does this mean for our applications? Will we need to redeploy anything?
• Stakeholders just wanted to know the impact. How long until it’s fixed? Will this happen again?

I quickly realized that my one size fits all explanation wasn’t working. Everyone was asking follow up questions because my response didn’t address their concerns directly. Instead of providing clarity, I was making things more confusing.

---

Learning to Communicate Better

After that incident, I made it a priority to learn how to communicate technical issues more effectively. I thought I was already clear in my explanations, but that war room made me realize that clarity is relative, it depends entirely on your audience.

That’s when I came across Minto’s Pyramid Principle, which completely changed how I structured my communication. The main idea is simple but powerful:

1. Always start with the conclusion: What happened?
2. Provide supporting details: Why did it happen?
3. Give additional context if needed: What’s being done about it?

Had I used this approach in the war room, my response would have looked something like this:

For stakeholders:
“We experienced an outage due to a misconfigured deployment that removed our DNS records, causing downtime for internal and external APIs. The issue was resolved in 45 minutes, and we are implementing validation steps to prevent this from happening again”

For engineers:
“A CloudFormation rollback applied an outdated DNS configuration, effectively deleting our Route 53 records. We manually restored them and confirmed propagation. Next steps involve enforcing stricter rollback policies and validating infrastructure updates before deployment”

For developers:
“The DNS issue prevented services from resolving hostnames, which is why the APIs were unreachable. No redeployment is needed, as everything is now functioning normally”

This approach immediately provides value to each audience without overwhelming them with unnecessary details. The result? Fewer questions, faster alignment and a much smoother incident response process.

---

Conclusion: Communication is a Skill, Not an Afterthought

After this incident I started applying the Minto Pyramid Principle in every major communication, whether it was an outage report, a design review, or even daily standups. More importantly, I found it especially useful when communicating with someone who had significantly more seniority than me.

Early in my career, I used to over explain things assuming that more details meant better clarity. But I quickly realized that the more senior the person, the less time they have to process unnecessary information. They are not looking for a deep dive into every possible scenario. You need to get to the point fast, highlight the key details and provide just enough context to make an informed decision.

If there’s one thing I learned, it’s this: it doesn’t matter how much you know if you can’t explain it well. The best engineers aren’t just the ones who write great code, they are the ones who can communicate complex ideas in a way that makes sense to others.

So if you ever find yourself in a war room, struggling to explain an issue, take a step back, structure your thoughts and start with the conclusion.