Module 4: Writing Technical Documents in Plain Language
7. Postmortems and Incident Writing
Description
Something broke in production. Payment failed for a group of users, the API was down for twenty minutes, a deploy took down login. It happens on every team, all the time, even the best ones. What separates a team that grows from one that lives putting out fires isn't the absence of incidents: it's what they write afterward. And that's where a document you've probably already heard named in English, and that sounded intimidating, comes in: the postmortem. I want you to leave this lesson seeing it for what it actually is, which isn't a trial or an English exam, but one of the most learnable, most templated pieces of writing, and one of the most generous toward anyone who still doubts their language skills.
A postmortem is the report a team writes after an incident to understand what happened, why, and what they're going to change so it doesn't happen again. The word comes from medicine — literally "after death," the analysis done on a body to find the cause — and in tech it means exactly that, transferred to a system: the case gets opened calmly, once there's no more fire, and studied with nobody pointing a finger. That last part has its own name in English, blameless, and it's not a moral decoration: it's a writing decision that completely changes whether the team genuinely learns or whether everyone writes defensively to cover themselves. You're going to see that a large part of writing a good postmortem is a matter of how you phrase it, not how much English you know.
In this lesson we separate two kinds of writing people confuse, with opposite rules: communication during the incident — the short messages you send while the fire's burning, in present tense and with partial information — and the after-the-fact report — the calm document you write the next day with the whole story already known. I'll give you the English incident vocabulary that repeats at every company (degraded, partial outage, mitigated, root cause, contributing factor), the real difference between root cause and contributing factor, the document's full structure with its English example, and the phrases that turn blaming writing into teaching writing.
Connection to the module: This is the module's last document type and the one with the most readers: a postmortem gets read by your team, your manager, sometimes the whole company. It uses everything you've already built: the plain language from lesson 2 (mandatory here, because a stressed, non-technical audience reads an incident report), the design doc's sectioned anatomy (lesson 3), and the ADR's decision trail (lesson 5) — in fact, a postmortem's corrective actions often turn into a new ADR. It's technical writing's final escalation: maximum exposure, maximum need for clarity, and the best proof that you can communicate under pressure without losing a professional tone.
Before we start: what this lesson assumes and what it doesn't
This guide doesn't teach English from zero, and neither does this lesson. I'm assuming you already read technical English with reasonable ease (B1 reading level: you understand an incident message without translating word by word, even if you sometimes look up a term). You don't need to speak well yet: the postmortem, just like the previous lesson's PR, is 100% written and asynchronous. You write with a safety net — you review, delete, compare against a template, and correct before anyone reads it. Nobody measures your accent in a document.
If reading an incident report in English leaves you completely lost, it's not that "you're not cut out for this": it's that you're still missing reading floor, and the honest move is to reinforce module 2 (technical English foundations) before continuing. There's no shortcut worth taking. But if you already understand what you read even though writing under an incident's shadow makes you nervous, you're exactly at the point this lesson was written for — and the language pressure drops a lot once you discover how many of these phrases are fixed and repeatable.
Part 1 — What a postmortem is and why "blameless"
What it is and why it matters
Think of the postmortem as an airplane's black box. When something goes wrong, nobody runs to ask whose fault it was: the black box gets recovered, what happened gets reconstructed minute by minute, and the result gets shared so the whole industry flies safer. The goal isn't punishing the pilot — it's the next flight not repeating the failure. A postmortem does the same thing with a software system: it reconstructs the incident with data, finds the cause, and produces concrete changes.
An incident resolved with no postmortem is a lesson thrown in the trash. The system came back up, sure, but the team didn't capture why it failed or how to prevent it from happening again. Writing is what turns a bad moment into knowledge that stays.
What "blameless" means and why the writing decides everything
Blameless means "with no blame": the document describes what failed in the system and the process, never who the bad person is. It's not that who ran the command gets ignored — it's that you assume, from the start, that no reasonable person breaks production on purpose, and that if a single human error could take down the system, the real problem is that the system allowed that error with no barrier at all.
This isn't kindness. It's the difference between a team that learns and one that hides. Look at it this way:
| If the postmortem blames people... | If the postmortem is blameless... |
|---|---|
| People write defensively, to cover themselves | People write the full truth, with no fear |
| Details that would look "bad" get hidden | Details revealing the real cause come to light |
| Next time, nobody reports on time out of fear | Next time, it gets reported fast and contained early |
| The person gets "fixed" (a scolding) | The system gets fixed (a new barrier) |
And here's the point that frees you as a Spanish speaker: writing blameless is, deep down, a concrete, copyable writing trick, not some subtle mastery of the language. It almost always comes down to moving the subject from the person to the system. It's the same rule you saw when receiving code review in the previous lesson — the enemy is "you" pointing at the person; the friend is talking about the system's behavior.
| ❌ Blames the person | ✅ Blameless (describes the system) |
|---|---|
| "Carlos deployed a broken config." | "A config change was deployed without a validation step to catch the error." |
| "The engineer forgot to run the migration." | "The deploy process did not enforce running pending migrations." |
| "Someone deleted the wrong table." | "The admin tool allowed deleting a production table without a confirmation step." |
| "QA missed this bug." | "There was no automated test covering the empty-cart case." |
Notice: the technical information is identical. Nobody's lying or covering up what happened. Only where the sentence points changed — and with that change, the document shifts from "find who's guilty" to "find the missing barrier." In English this is achieved mostly with selective passive voice ("a config change was deployed") and with the system as the subject ("the deploy process did not enforce..."). It's one of the very few places where the passive voice, which lesson 2 told you to avoid, is exactly the right tool.
Part 2 — Incident English (the vocabulary that repeats)
Incidents have their own vocabulary, short and universal. It shows up the same at a startup and at Google. Learning it is like learning traffic signs: there are few of them and they always mean the same thing. This is the table you'll consult the most in this lesson.
States and severity
| Term in English | What it means | How it's used |
|---|---|---|
| Outage | The service is down, not working | "We had a 15-minute outage." |
| Partial outage | Part of the service is down; the rest works | "Checkout was down, but browsing worked — a partial outage." |
| Degraded / degraded performance | It works, but slow or with intermittent errors | "The API was degraded: ~20% of requests timed out." |
| Elevated error rate | Errors rise above normal | "We saw an elevated error rate on the login endpoint." |
| Down | Down (informal, widely used) | "The database was down for 8 minutes." |
| Impact | Who and what was affected | "Impact: ~3,000 users could not log in." |
| Blast radius | The reach of the damage (how far it went) | "The blast radius was limited to the EU region." |
The incident life cycle
| Term in English | What it means |
|---|---|
| Detected | The moment someone or something noticed the problem |
| Investigating | The cause is being looked for; not known yet |
| Identified | The cause is now known |
| Mitigated | The damage has stopped (users no longer suffer it), but the underlying cause may still be there |
| Resolved | Fully closed: cause fixed and service back to normal |
The distinction between mitigated and resolved is one of the most useful and most misunderstood ones. Mitigated is "I stopped the bleeding" — for example, you restarted the server and users can get in again. Resolved is "I healed the wound" — you found why memory was filling up and fixed it so it won't happen again. A restart usually mitigates; it almost never resolves. Confusing them makes a team declare victory too early and the incident comes back that same night.
Root cause vs. contributing factor
These two terms are a postmortem's technical heart, and confusing them is the most common analysis mistake. Worth separating them clearly.
- Root cause: the underlying failure that, had it not existed, the incident would not have happened. It's the tree's root.
- Contributing factor: something that made the incident worse, longer, or harder to detect, but that on its own wouldn't have caused it. These are the branches.
One example makes the difference obvious:
Root cause: "A database connection pool was configured with a maximum of 10 connections. Under peak traffic, all connections were held, and new requests waited until they timed out."
Contributing factor 1: "The alert for connection-pool saturation was set to 95%, so it fired only after the outage had already started."
Contributing factor 2: "The on-call runbook did not mention the connection pool, so the responder spent 12 minutes looking in the wrong place."
The root cause explains why it broke; the contributing factors explain why it took so long to see and fix. A good postmortem almost always has one root cause and several contributing factors — and often the most valuable improvements come from the factors, not the root (a better alert, an updated runbook). Honesty matters here: forcing everything into one simplistic root cause ("it was human error") papers over exactly the system factors you could actually fix.
Part 3 — Communication DURING the incident
There are two completely different types of writing around an incident, and mixing them up is a classic mistake. Let's start with the one that happens while the fire's burning: the short messages you post in the incident channel (Slack, Teams) or publish on a status page for users.
What it is and what rules govern it
A status update during the incident is a brief message, in present tense, with the information you have this very minute — which is almost always incomplete. Its job isn't explaining the cause (you don't know it yet); it's telling people that you're on it, what's known, and when the next update will come. Silence is the worst enemy here: if a user sees no sign of life, they assume nobody's looking.
Three golden rules for this moment:
- Present tense and factual. Say what you know, not what you think. "We are investigating." Not "It's probably the database" if you haven't confirmed it yet.
- Don't promise timelines you don't control. Never "fixed in 10 minutes." Yes to "next update in 15 minutes." — you promise your next message, not the fix.
- No blame and no jargon. Stressed, sometimes non-technical people read this. Plain language, zero proper names.
Templates by phase (copy and adapt)
Almost every provider in the world uses these same four phases. Recognize them and you have 90% of the vocabulary:
Investigating (we just detected it, we don't know the cause): "We are investigating reports of errors when logging in. We'll share an update in 15 minutes." (Investigando reportes de errores al iniciar sesión. Próxima actualización en 15 minutos.)
Identified (we now know the cause): "We have identified the cause — a configuration change is being rolled back now. Next update in 15 minutes." (Identificamos la causa; estamos revirtiendo un cambio de configuración.)
Monitoring (we applied the fix, watching that it holds): "A fix has been applied and login is working again. We are monitoring to confirm full recovery." (Aplicamos un arreglo y el login funciona; monitoreando para confirmar la recuperación total.)
Resolved (closed): "This incident is resolved. Login has been fully operational since 14:30 UTC. A postmortem will follow." (Incidente resuelto; el login opera con normalidad desde las 14:30 UTC. Publicaremos un postmortem.)
Notice how every message ends pointing to the next one: "next update in 15 minutes" or "a postmortem will follow." That closing keeps trust alive — people tolerate an incident surprisingly well if they feel someone's communicating it in an orderly way.
What to expect: the first time you have to write live with adrenaline high, you're going to want to write long paragraphs explaining everything. Resist it. In the middle of an incident, less is more: one clear line every 15 minutes is worth more than an essay. And since these four templates are fixed, you can keep them pinned in a note and fill in the blank — English stops being the problem exactly when you'd appreciate that the most.
Part 4 — The AFTER-THE-FACT report: the written postmortem
Once the incident's closed and everyone's slept, comes the second kind of writing, the opposite of the first: calm, in the past tense, with the whole known story. There's no rush here. This is where you assemble the document the team's going to read to learn. It has a standard structure; once you have it, writing the postmortem is filling in sections, not inventing from scratch.
The standard structure
| Section (in English) | What it answers | Special care |
|---|---|---|
| Summary | In 2-3 lines: what happened and how long it lasted | The first thing read; make it self-contained |
| Impact | Who it affected, how much, in numbers | Quantify: users, %, money, time |
| Timeline (UTC) | What happened minute by minute | Always in UTC; absolute times |
| Detection | How and when we noticed it | Did an alert catch it or a user? |
| Root cause | The underlying failure | Just one, well explained |
| Contributing factors | What made it worse or longer | Several; this is where the gold comes out |
| Resolution / Mitigation | How it got stopped and how it got closed | Separate mitigation from resolution |
| Action items | What we're going to change | With an owner and a date, always |
Why the timeline goes in UTC
UTC (Coordinated Universal Time) is the world's reference time, the same for everyone regardless of country. On a distributed team — you in Mexico, a colleague in India, another in Germany — if everyone writes their local time, the timeline becomes an impossible puzzle to reconstruct. UTC is the neutral agreement: every time in the postmortem, always, in UTC. Written like this: 14:32 UTC. It's a small detail that screams "I know how international teams work."
A real postmortem, in English
Here's a complete, short one. Read it in full: it's your template.
# Postmortem: Login outage on 2026-03-14
## Summary
On 2026-03-14, the login service was unavailable for 22 minutes
(14:08–14:30 UTC). Users could not sign in. Browsing and checkout
were not affected (partial outage).
## Impact
- ~3,200 users were unable to log in during the window.
- ~180 checkout sessions were abandoned (users could not re-authenticate).
- No data was lost.
## Timeline (UTC)
- 14:05 — A configuration change was deployed to the auth service.
- 14:08 — Error rate on POST /login rose from <1% to ~85%.
- 14:11 — PagerDuty alerted the on-call engineer.
- 14:14 — On-call began investigating; posted "Investigating" status.
- 14:22 — The bad config change was identified as the cause.
- 14:26 — The change was rolled back.
- 14:30 — Error rate returned to normal. Incident mitigated.
- 15:10 — A validation check was added to the deploy pipeline. Resolved.
## Detection
The incident was detected automatically by the error-rate alert,
3 minutes after impact began. No users had to report it first.
## Root cause
A configuration change set the auth token expiry to 0 seconds. Every
issued token was considered expired immediately, so all login attempts
were rejected. The change passed review because the value looked valid
in isolation and there was no test for token expiry > 0.
## Contributing factors
- The deploy pipeline had no validation step for config values, so an
invalid setting reached production unblocked.
- The on-call runbook did not cover auth-config rollbacks, adding
~4 minutes to the response.
## Resolution and mitigation
- Mitigation (14:26): rolled back the config change; login recovered.
- Resolution (15:10): added a pipeline check that rejects a token
expiry of 0 before deploy.
## Action items
| Action | Owner | Due |
|---|---|---|
| Add config validation to the deploy pipeline | @maria | 2026-03-21 |
| Add a test for token expiry > 0 | @dev-team | 2026-03-19 |
| Add auth-config rollback steps to the runbook | @luis | 2026-03-18 |Action items: the detail almost everyone gets wrong
The most important and most neglected section. A corrective action with no owner and no date isn't an action: it's a nice wish nobody's going to act on. The rule is strict and simple:
Every action item carries one name (owner) and one date (due date). No exceptions.
| ❌ Vague action (nothing happens) | ✅ Real action (someone does it) |
|---|---|
| "We should add better validation." | "Add config validation to the deploy pipeline — @maria, due 2026-03-21." |
| "Improve monitoring." | "Add an alert for token-expiry misconfig — @luis, due 2026-03-25." |
| "Update the docs." | "Add auth rollback steps to the runbook — @ana, due 2026-03-18." |
Also notice the verb: it opens with an imperative in English (Add, Improve is better as a concrete "Add..."), just like the previous lesson's README executable instructions. An action item reads like a clear order for the system, not a reflection.
Part 5 — Blameless writing in practice
You already saw the principle in Part 1. Now the fine-grained moves, because this is where a nervous Spanish speaker gives themselves away the most, usually from writing defensively or from literally translating an apology the original didn't need.
Talk about actions and systems, not people
The pattern is the same one from the whole module: shift the focus from "who" to "what." In a timeline you can name roles (the on-call engineer, the reviewer) because it's necessary for the timeline, but never in an accusatory tone, and you never hang the root cause on a person.
| ❌ Focused on the person | ✅ Focused on the system |
|---|---|
| "The reviewer approved a bad change." | "The change passed review because there was no test covering this case." |
| "He didn't check the logs." | "The runbook didn't point to the relevant logs, so they weren't checked early." |
| "They pushed on a Friday." | "The change was deployed with no automated rollback available." |
Don't turn the postmortem into an apology
An incident isn't a moral failing. The tone is analytical and neutral, not remorseful. Writing "we are so sorry, this was a terrible failure on our part" throughout the whole document adds nothing technical and projects insecurity. A brief acknowledgment of the user impact is fine; the rest is cold analysis.
| ❌ Apologetic/embarrassed tone | ✅ Analytical tone |
|---|---|
| "We deeply apologize for this embarrassing mistake." | "This incident affected ~3,200 users. Here is what happened and what we're changing." |
| "This should never have happened." | "This was possible because the pipeline had no config validation. That gap is now closed." |
| "I feel terrible about this." | "The root cause is understood and the fix is deployed." |
The vocabulary that sounds professional under pressure
A handful of set phrases that show up in almost every postmortem and that you can reuse as-is:
- "The incident was detected automatically by..."
- "Impact was limited to..."
- "As an immediate mitigation, we..."
- "The root cause was..." / "Contributing factors included..."
- "To prevent recurrence, we will..."
- "No data was lost." / "No customer data was exposed." (When it applies: say it, it reassures.)
What to expect: your first few postmortems are going to cost you more from the defensive-writing reflex than from the English. You're going to want to explain why it wasn't your fault. Let it go. A blameless team already knows it wasn't your fault — they assume nobody broke anything on purpose. When you stop defending yourself and calmly describe the system, two things happen at once: the document gets better and your English flows better, because system sentences are much easier and much more templated than emotional ones.
Closing: why you can actually do this
An incident is scary. Writing about it in English, more so. But look at what you actually have in your hands by the end of this lesson: not "writing good English" — that's an ocean — but a handful of finite, copyable pieces. Four status templates (investigating / identified / monitoring / resolved). A vocabulary table that repeats across the entire industry (outage, degraded, mitigated, root cause, contributing factor). An eight-section report structure that gets filled in, not invented. And one writing trick, blameless, that at the language level comes down to moving the subject from the person to the system. You can count them on your fingers. You paste them into a file. You reuse them at every incident in your career.
And like the previous lesson's PR, the postmortem works in your favor by being written and unhurried: you draft it the next day, calmly, comparing it against this example, correcting it before anyone reads it. The incident was the moment of pressure; the document isn't. A Spanish-speaking developer writing a clear, blameless postmortem in plain English is, for any international team, one of the strongest maturity signals there is — and you just saw it's made of parts you can have ready ahead of time.
In the module's last lesson you bring it all together: you'll write a complete design doc in plain English about a system of your own, with its ADR and its README. The postmortem you learned today is the other side of that same coin — the design doc says how you expect something to work; the postmortem, what you learned when it didn't. Both are the same clear writing, and both are seniority evidence you can produce without anyone's permission.
Recap in a table
| Situation | The phrase or piece that saves you |
|---|---|
| Announcing you're investigating | "We are investigating... Next update in 15 minutes." |
| Confirming the cause | "We have identified the cause..." |
| Closing the incident live | "This incident is resolved. A postmortem will follow." |
| Describing the service's state | outage / partial outage / degraded / mitigated / resolved |
| Separating the "why" from the "why it took so long" | root cause (one) vs. contributing factors (several) |
| Writing without blaming | Move the subject: "A change was deployed...", not "Carlos deployed..." |
| Writing a real action | "[Verb] ... — @owner, due YYYY-MM-DD." |
| Closing calmly | "To prevent recurrence, we will... No data was lost." |
Exercises
These exercises train the lesson's four skills: writing with no blame, telling root cause apart from contributing factor, picking the right phrase for the incident's phase, and turning a vague action into a real one. Work through them in writing before opening the solution.
Exercise 1 — Rewrite with no blame. This fragment blames a person:
"Ana forgot to add a timeout to the payment API call, and that's why checkout hung for 12 minutes."
Rewrite it in English following the blameless pattern: the subject must be the system or the process, not the person, with no technical detail lost.
See solution
"The payment API call had no timeout configured, so checkout hung for 12 minutes when the downstream service stopped responding."
Why this works: the technical information is identical — a timeout is missing, checkout hung for 12 minutes — but the sentence's subject went from "Ana" to "the payment API call." Nobody's covering anything up; it just points at the missing barrier, not whoever didn't put it there.
Exercise 2 — Root cause or contributing factor. An engineer manually rotated an API key at 03:00 and forgot to update it in the payments service config; for two hours every webhook call failed. Classify each statement as root cause or contributing factor:
a) "The payments service was configured with the old API key, which had been rotated and was no longer valid at the provider." b) "There was no automated alert for authentication failures on webhook calls, so the team only noticed after customers complained." c) "The runbook for key rotation did not include a step to update the payments service config."
See solution
- a) Root cause. It's the underlying failure: had the key not been left outdated in that config, the incident wouldn't have happened.
- b) Contributing factor. It didn't cause the failure, but it lengthened how long the team took to find out.
- c) Contributing factor. It also didn't cause the failure, but it explains why the step to update the config got skipped — it's the missing process barrier.
Why this works: the question separating the two types is "would this alone have caused the incident?" Only (a) answers yes; (b) and (c) are branches that made the problem worse or longer, not the root.
Exercise 3 — Write the right-phase message. Your API's error rate rose to 10%. A minute ago your team confirmed the cause is a recent deploy, and it's being rolled back right now — they don't yet know whether the rollback has fully fixed it. What phase of the life cycle are you in (investigating / identified / monitoring / resolved) and what message do you write for the status channel?
See solution
Phase: identified. The cause is now known, but the fix hasn't yet been confirmed as successful (that would be monitoring) and the incident isn't closed (that would be resolved).
Message: "We have identified the cause — a recent deployment is being rolled back now. Next update in 15 minutes."
Why this works: the phase is decided by what you know with certainty this minute, not by how optimistic you feel. Knowing the cause isn't the same as having confirmed recovery; jumping ahead to say resolved or monitoring too early breaks trust if the problem comes back.
Exercise 4 — From vague action to real action. Your team wrote this corrective action: "We should improve our alerting." Turn it into a real action with an owner and a date, thinking about Exercise 2's incident (missing alert for authentication failures on webhooks).
See solution
"Add an alert for authentication failures on webhook calls — @maria, due 2026-04-10."
Why this works: a real action opens with an imperative verb, describes something concrete that can be marked as done, and carries an owner and a date — without those two pieces, "improve our alerting" is a nice wish, not a commitment.
Summary and next step
Before moving on to lesson 8, you should be able to, without scrolling back up:
- Tell communication during the incident (status update, present tense, partial information) apart from the postmortem afterward (past tense, complete story).
- Use the status vocabulary (
outage,partial outage,degraded,mitigated,resolved) and explain whymitigatedisn't the same asresolved. - Separate
root cause(one) fromcontributing factors(several) in a concrete incident. - Write a complete postmortem in English with its eight sections (summary, impact, timeline in UTC, detection, root cause, contributing factors, resolution, action items).
- Write blamelessly by moving the subject from the person to the system, and write an action item with an owner and a date.
If any of these points still trips you up, go back to the corresponding part before moving on — lesson 8's project assumes you already own these pieces.
Bridge to lesson 8. The module closes with the project: a complete design doc in plain English about a system of your own, with its ADR and README integrated. The postmortem you just learned is the other side of that same coin — the design doc says how you expect something to work; the postmortem, what you learned when it didn't. There you'll see how the module's four pieces (plain language, design doc, ADR, README/postmortem) assemble into a single portfolio document.
Resources
- Google SRE Book — Postmortem Culture: Learning from Failure — the chapter that originated blameless postmortem culture across the industry; the direct source for this lesson's blameless approach.
- Atlassian — How to run a blameless postmortem — a practical guide on how to facilitate writing and running a postmortem meeting without falling into individual blame.
- PagerDuty — Postmortems — an open guide with a template, checklist, and analysis questions for writing a postmortem start to finish.
- PagerDuty — Incident Response — open documentation on an incident's life cycle (detection, investigation, mitigation) and how to communicate it as it happens.